%% LyX 2.4.0-beta3-devel created this file. For more info, see https://www.lyx.org/. %% Do not edit unless you really know what you are doing. \documentclass[english,tableposition=top]{report} \usepackage{lmodern} \renewcommand{\sfdefault}{lmss} \renewcommand{\ttdefault}{lmtt} \usepackage[T1]{fontenc} \usepackage{textcomp} \usepackage[utf8]{inputenc} \setcounter{secnumdepth}{3} \usepackage{color} \definecolor{shadecolor}{rgb}{0.667969, 1, 1} \usepackage{babel} \usepackage{array} \usepackage{cprotect} \usepackage{wrapfig} \usepackage{booktabs} \usepackage{framed} \usepackage{url} \usepackage{multirow} \usepackage{varwidth} \usepackage{amsmath} \usepackage{amssymb} \usepackage[pdfusetitle, bookmarks=true,bookmarksnumbered=true,bookmarksopen=true,bookmarksopenlevel=2, breaklinks=true,pdfborder={0 0 1},backref=section,colorlinks=true] {hyperref} \makeatletter %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% LyX specific LaTeX commands. \providecommand{\LyX}{\texorpdfstring{\ensureascii{% L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}}{LyX}} \newcommand{\noun}[1]{\textsc{#1}} \DeclareRobustCommand*{\lyxarrow}{% \@ifstar {\leavevmode\,$\triangleleft$\,\allowbreak} {\leavevmode\,$\triangleright$\,\allowbreak}} %% Because html converters don't know tabularnewline \providecommand{\tabularnewline}{\\} %% Variable width box for table cells \newenvironment{cellvarwidth}[1][t] {\begin{varwidth}[#1]{\linewidth}} {\@finalstrut\@arstrutbox\end{varwidth}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Textclass specific LaTeX commands. \newenvironment{centred}% {\begin{center}}{\end{center}} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% User specified LaTeX commands. \usepackage{numerica} \usepackage{mleftright} \usepackage{upquote} \usepackage{xfrac} \usepackage{xurl} \newcommand\rel{\,\varrho\;} \DeclareMathOperator{\erf}{erf} \DeclareMathOperator{\gd}{gd} \reuse{} \newcommand\vsp{\vphantom{I^{I^I}}} \newcommand\dsp{\vphantom{I_{I_I}}} \makeatother \begin{document} \title{\texttt{numerica}~\\ {\large version 3.0.0}} \author{Andrew Parsloe\\ (\url{ajparsloe@gmail.com})} \maketitle \begin{abstract} The \texttt{numerica} package defines a command \verb`\nmcEvaluate` (short-name form \verb`\eval`) to wrap around mathematical expressions in the LaTeX form in which they are typeset and numerically evaluate them. For programs (like \LyX ) with a preview facility, or for compile-as-you-go systems, interactive back-of-envelope calculations and numerical exploration are possible within the document being worked on. \end{abstract} \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \begin{itemize} \item This document applies to version 3.0.0 of \texttt{numerica}. \item \texttt{numerica} requires a \LaTeXe{} system from October 2020 or later (when \texttt{xparse} became available in \LaTeXe{} systems). \item The package requires \texttt{amsmath} and \texttt{mathtools}, is compatible with the \texttt{mleftright} and \texttt{xfrac} packages, and `knows about' some symbols from \texttt{amssymb}. \item I refer many times in this document to \emph{Handbook of Mathematical Functions}, edited by Milton Abramowitz and Irene A. Stegun, Dover, 1965, abbreviated to \emph{HMF}, and often followed by a number like 1.2.3 to locate the actual expression referenced. \item Version 3.0.0 of \texttt{numerica} \begin{itemize} \item dispenses with a configuration file (\verb`numerica.cfg`) but adds three package options: \begin{itemize} \item \verb`comma` sets the comma as the decimal point; items in the variable=value list must then be separated by semicolons; \item \verb`rounding`=$n$ sets the default rounding value to the integer $n$; \item \verb`approx` replaces the default \verb`=` between formula and result in displays with \verb`\approx` ($\approx$); \end{itemize} \item enables outputting results as (approximate) fractions with integer numerators and denominators in both slash and \verb`\frac` forms; \item allows use of \LaTeX{} braces for delimiting arguments to functions like \verb`\sin` and \verb`\cos` to handle complicated arguments in (e.g.) Fourier series; the previous \texttt{()=0}, \texttt{1}, \texttt{2} setting for this is removed; \item enables multiple formulas to be evaluated within the one \verb`\eval` command; and \item provides enhanced treatment of mathematical environments for the presentation of results, especially for such multiple evaluations, with the \verb`env` key in the settings option (which makes the \verb`*` key obsolete); \item defines a \verb`\degree` command and uses it as an alternative to the \verb`o` setting for specifying angles in degrees; \item allows nested commands to be evaluated to a specified rounding value (rather than insisting that they be evaluated to maximum precision); \item accepts the use of spaces to group blocks of digits in numbers in the variable=value list and formula (with the setting \verb`1s2=1`); \item resolves the `leading space' issue with the \verb`\macros` command when a user-defined macro begins with an expandable token; \item \emph{continues \ldots} \end{itemize} \end{itemize} \end{shaded}% \end{minipage} \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \begin{itemize} \item Version 3.0.0 of \texttt{numerica}~\emph{(continued)} \begin{itemize} \item reworks (again!) the \verb`\reuse` command to simplify its use, and \item removes the \verb`reuse` \emph{setting} of \verb`\eval` (not the command); now \emph{only} the numerical result is saved, either as a decimal or in scientific notation or in fraction form (but without math delimiters or variable=value list); \item adds the \LaTeX{} form of a result to the debug display (\verb`dbg=11`); \item adds warnings with line numbers to the \LaTeX{} log file for \texttt{numerica} errors (which continue to be displayed in the pdf); \item accepts the use of \verb`a-`, \verb`ar-` or \verb`arc-` prefixes for the inverses of all six hyperbolic functions so that, for instance, \verb`\asinh`, \verb`\arsinh`, and \verb`\arcsinh`, displaying as $\asinh$, $\arsinh$ and $\arcsinh$, can be used (rather than only \verb`\asinh` as before); \item accepts the \verb`\sfrac` command from the \texttt{xfrac} package, producing elegant slash fractions like $\sfrac{355}{113}$; \item accepts commands of the \texttt{mleftright} package; \item accepts \verb`\mkern` and \verb`\mskip` commands in formulas; \item defines the commands \verb`\comma` and \verb`\equals` (expanding to \verb`,` and \verb`=`) for use in the settings option, as distinct from the `bare' marks used in formulas; \item fixes bugs that could occur: (i) when raising an $n$-th root to a power; (ii) when using a dot with \verb`\left`, \verb`\right`; and (iii) when using a non-integer in the first argument of \verb`\binom`; \item amends and adds to documentation. \end{itemize} \end{itemize} \end{shaded}% \end{minipage} \tableofcontents{} \chapter{Introduction} \label{chap:Introduction}\texttt{numerica} is a \LaTeX{} package offering the ability to numerically evaluate mathematical expressions in the \LaTeX{} form in which they are typeset. There are a number of packages which can do calculations in \LaTeX ,\footnote{A simple search finds the venerable \texttt{calc} in the \LaTeX{} base, \texttt{calculator }(including an associated \texttt{calculus} package), \texttt{fltpoint}, \texttt{fp} (\emph{fixed} rather than floating point), \texttt{spreadtab} (using either \texttt{fp} or \texttt{l3fp} as its calculational engine) if you want simple spreadsheeting with your calculations, the elaborate \texttt{xint}, \texttt{pst-calculate} (a limited interface to \texttt{l3fp}), \texttt{l3fp} in the \LaTeX 3 kernel, and \texttt{xfp}, the \LaTeX 3 interface to \texttt{l3fp}. Other packages include a calculational element but are restricted in their scope. (\texttt{longdivision} for instance is elegant, but limited only to long division.)} but those I am aware of all require the mathematical expressions they operate on to be changed to an appropriate syntax. Of these packages \texttt{xfp} comes closest to my objective with \texttt{numerica}. For instance, given a formula \begin{centred} \verb`\frac{\sin (3.5)}{2} + 2\cdot 10^{-3}` \end{centred} (in a math environment), this can be evaluated using \texttt{xfp} by transforming the expression to \verb`sin(3.5)/2 + 2e-3` and wrapping this in the command \verb`\fpeval`. In \texttt{numerica} you don't need to transform the formula, just wrap it in an \verb`\eval` command: \begin{centred} \verb`\eval{ \frac{\sin (3.5)}{2} + 2\cdot 10^{-3} }`. \end{centred} (For the actual calculation see §\ref{subsec:introBasicProcedure}.)\texttt{ } \texttt{numerica}, like \texttt{xfp} and a number of other packages, uses \texttt{l3fp} (the \LaTeX 3 floating point module in \texttt{l3kernel} and since February 2020 available in \LaTeXe{} distributions) as its calculational engine. The main command of the package, \verb`\nmcEvaluate`, short-name form \verb`\eval`, in many ways acts as a pre-processor to \texttt{l3fp}, converting mathematical expressions written in the \LaTeX\texttt{ }form in which they will be typeset into an `fp-ified' form that is digestible by \texttt{l3fp}. The aim is for the command to act as a wrapper around \LaTeX{} formulas, processing them into a form that is digestible by \texttt{l3fp} and allows compilation to \texttt{pdf} to take place. Ideally, one should not have to make \emph{any} adjustment to a formula, although any text on Fourier series suggests that hope in full generality is delusional. Surprisingly often however it \emph{is} possible. We shall see shortly that even complicated formulas like \[ \cos\tfrac{m}{n}\pi-(1-4\sin^{2}\tfrac{m}{3n}\pi)\frac{\sin\tfrac{1}{n}\pi\sin\tfrac{m-1}{n}\pi}{2\sin^{2}\tfrac{m}{3n}\pi}, \] and \[ \left(\frac{1-4\sin^{2}\tfrac{m}{3n}\pi}{2\sin^{2}\tfrac{m}{3n}\pi}\right)\sin\tfrac{2m-3}{3n}\pi\sin\tfrac{m-3}{3n}\pi, \] \noindent can be evaluated `as is' (see below, §\ref{subsec:introReassurance}). There is no need to shift the position of the superscript $2$ on the sines, no need to parenthesize the arguments of \verb`\sin` and \verb`\cos`, no need to insert asterisks to indicate multiplication, no need to change the \verb`\frac` and \verb`\tfrac`-s to slashes, \texttt{/}, and in the second expression no need to delete the \verb`\left` and \verb`\right` that qualify the big parentheses (in the underlying \LaTeX ). Of course, if there are variables in an expression, as in these examples, they will need to be assigned values; that is unavoidable. And how the result of the evaluation is displayed also requires specifying, but the aim is always: to evaluate mathematical expressions in \LaTeX{} with as little adjustment as possible to the form in which they are typeset. \texttt{numerica} is written in \texttt{expl3}, the programming language of the \LaTeX 3 project, now incorporated into the \LaTeX{} kernel. It uses the \LaTeX 3 module \texttt{l3fp} (since early 2020 part of a standard \LaTeXe{} distribution) as its calculational engine. This enables floating point operations to 16 significant figures, with exponents ranging between $-10000$ and $+10000$. Many functions and operations are built into \texttt{l3fp} – arithmetic operations, trigonometric, exponential and logarithm functions, factorials, absolute value, max and min. Others have been constructed for \texttt{numerica }from \texttt{l3fp} ingredients – binomial coefficients, hyperbolic functions, sums and products – but to the user there should be no discernible difference. Associated packages provide for additional operations: iteration of functions, finding zeros of functions, recurrence relations, mathematical table building. \section{How to use \texttt{numerica}} The package is invoked in the usual way: put \begin{verbatim} \usepackage[]{numerica} \end{verbatim} \noindent in the \LaTeX{} preamble. \texttt{numerica} requires the \texttt{amsmath} and \texttt{mathtools} packages and loads these automatically. \texttt{numerica} will also accept use of some relation symbols from the \texttt{amssymb} package (see §\ref{subsec:evalBoolean-output}), all commands from the \texttt{mleftright} package, and the \verb`\sfrac` command from \texttt{xfrac} (part of the \texttt{l3packages} bundle), provided these last three packages have been loaded by the user. \subsection{Package options} \label{subsec:introPackagesOptions}Version 2 of \texttt{numerica} had no package options. The options available in version 1 that gave access to commands for iteration, finding zeros, math-table making, etc., were discontinued. That functionality became available in associated but separate \LaTeX{} packages (see below §\ref{subsec:introAssociated-packages}). With version 3.0.0 some package options have been added and the possible use of a configuration file dispensed with. The current options available with version 3.0.0 are: \begin{itemize} \item \verb`comma` If present, a decimal point is denoted by a comma (more exactly, an unspaced comma). If absent, a decimal point is denoted by a dot (period, full stop, also unspaced). The choice – \verb`comma` present, \verb`comma` absent – has consequences for the item separator in the variable=value list and $n$-ary functions (see §\ref{subsec:introDecPtItemSeps}), and the item separator in the main argument of the \verb`\eval`, \verb`\macros` and \verb`\constants` commands; see below §\ref{subsec:introDecPtItemSeps}. \begin{itemize} \item `Out of the box' the \verb`comma` option is not used and the decimal point is a dot. \end{itemize} \item \verb`rounding=` The rounding value. The value of \verb`` determines how many digits after the decimal point are displayed in numerical results (see §\ref{subsec:evalRounding-value}). `Out of the box' the value is set to $6$. \item \verb`approx` sets the default relation linking \emph{formula} and \emph{result} in displays from \verb`=` to \verb`\approx` (displaying as $\approx$). (The \verb`eq` setting (§\ref{subsec:settingsRelationSymbol}) is available to change the relation for individual calculations.) \end{itemize} Thus a possible invocation of \texttt{numerica} might be \begin{verbatim} \usepackage[comma,rounding=4,approx]{numerica} \end{verbatim} meaning that the decimal point is an unspaced comma, the default rounding value is $4$, and \verb`\approx` is inserted between formula and numerical result in (some) displays. Alternatively, \begin{verbatim} \usepackage{numerica} \end{verbatim} means the decimal point is an unspaced dot, the rounding value is $6$, and the display of (some) results is in the form \emph{formula=result}. \textbf{This is how} \texttt{\textbf{numerica}} \textbf{is invoked for the present document.} \subsubsection{\texttt{numerica.cfg}} Previous versions of \texttt{numerica} supported use of a configuration file for setting various default values. With version 3.0.0, this has been dispensed with. Now, \texttt{numerica} supports (currently) the three package options mentioned. On review, most of the \texttt{.cfg} settings did not feel like ones that realistically qualified as package-level settings. For calculation-level default values, see Chapter~\ref{chap:settingsSettings}. \subsubsection{Associated packages} \label{subsec:introAssociated-packages}Currently there are two of these, \texttt{numerica-plus} and \texttt{numerica-tables}. They are loaded with the familiar \verb`\usepackage` command in the document preamble and require \texttt{numerica} to be loaded. This is different from version 2 where calling \texttt{numerica-plus} or \texttt{numerica-tables} automatically loaded \texttt{numerica}.\texttt{ }I think it is clearer to do this in two explicit steps. Neither package will function without \texttt{numerica} loaded. Thus putting \begin{verbatim} \usepackage[]{numerica} \usepackage{numerica-plus} \end{verbatim} in the preamble of your document gives access to the commands \verb`\nmcIterate`, \verb`\nmcSolve`, and \verb`\nmcRecur` of \texttt{numerica-plus} and of course also to the commands in \texttt{numerica}. \verb`\nmcIterate` enables the iteration of functions of a single variable, including finding fixed points and, by means of Newton-Raphson iteration, finding zeros. \verb`\nmcSolve` enables the solving of equations of the form $f(x)=0$ (i.e.\ finding zeros) by bisection, or the finding of local maxima or minima of a function of one variable. \verb`\nmcRecur` enables the calculation of terms in recurrence relations, like the terms of the Fibonacci series, or othogonal polynomials defined recurrently. In all three cases, see the associated document \verb`numerica-plus.pdf` for details. If you enter \begin{verbatim} \usepackage[]{numerica} \usepackage{numerica-tables} \end{verbatim} in the preamble of your document you gain access to the command \verb`\nmcTabulate`, which enables the creation of (possibly multi-column) tables of function values and makes available most of the table formats used in \emph{HMF} (and also to the commands in \texttt{numerica}). See the associated document \verb`numerica-tables.pdf` for details. \subsection{Decimal point and item separators} \label{subsec:introDecPtItemSeps}From version 3.0.0 of \texttt{numerica} the trio of marks {\ttfamily\verb`.,;`} have different functions depending as the package is called without or with the \verb`comma` option. Without the comma option, the decimal point is a dot (period, full stop) and the variable=value list (§\ref{sec:evalVv-list}) is punctuated with commas. There is no ambiguity in a list like \verb`[g=9.81,u=1,t=0.5]` nor in the arguments of $n$-ary functions (§\ref{sec:calc-n-ary-functions}) like \verb`\max`, \verb`\min`, \verb`\gcd`, e.g.\ \verb`\gcd(63,231)`, although the presence of such functions in the vv-list needs protective braces, e.g.\ \verb`[x={\min(\pi,e,\phi,\gamma)},y=2]`. But if the decimal point is a comma, then its use as a separator in these lists is problematic. For that reason, with the \verb`comma` package option, \texttt{numerica} uses a \emph{semicolon} to punctuate the variable=value list and the argument lists of $n$-ary functions: \verb`[g=9,81;u=1;t=0,5]`, \verb`\max(6,1;2e;\gamma\pi^2)`. This is in line with ISO 80000 Part 2, section 3 which reads: `A comma, semicolon or other appropriate symbol can be used as a separator between numbers or expressions. The comma is generally preferred, except when numbers with a decimal comma are used.' However, rather than the gently permissive language of the standard, \texttt{numerica} \emph{insists} on semicolons for separating items when the \verb`comma` package option is used. In summary, the trio of punctuation marks \verb`.,;` are used in \texttt{numerica} like this: when the \verb`comma` package option is \emph{not} used, the marks function as \begin{itemize} \item \verb`.` = decimal point \begin{itemize} \item also \LaTeX{} dot signifying `no delimiter' when used with \verb`\left`, \verb`\right` etc. \end{itemize} \item \verb`,` = item separator in the variable=value list \begin{itemize} \item also argument separator in $n$-ary functions (\verb`\max`, \verb`\min`, \verb`\gcd`) \item also formula separator in the main argument of \verb`\nmcEvaluate` for multi-formula calculations \end{itemize} \end{itemize} or, when the \verb`comma` package option \emph{is} used, as \begin{itemize} \item \verb`.` = \LaTeX{} dot signifying `no delimiter' when used with \verb`\left`, \verb`\right` etc. \item \verb`,` = decimal point \item \verb`;` = item separator in the variable=value list \begin{itemize} \item also argument separator in $n$-ary functions (\verb`\max`, \verb`\min`, \verb`\gcd`), \item also formula separator in the main argument of \verb`\nmcEvaluate` for multi-formula calculations \end{itemize} \end{itemize} Note, in both cases, that if a formula involves an $n$-ary function (at present only \verb`\max`, \verb`\min`, or \verb`\gcd`) then it's argument will need to be hidden in braces to avoid being interpreted as containing multi-formula separators. Alternatively (and better) there is a setting that allows a different character to be used as the multi-formula separator for a calculation, e.g. \verb`ff=|` ; see §\ref{subsec:introMult-formula-calculations} and §\ref{subsec:settingsMulti-formula-separator}. \subsection{Basic procedure} \label{subsec:introBasicProcedure}A simple example of how \texttt{numerica} is used is provided by the document \begin{verbatim} \documentclass{article} \usepackage{numerica} \begin{document} \eval{$ mc^2 $}[m=70,c=299792458][8x] \end{document} \end{verbatim} \noindent There is a formula, \verb`mc^2`, between math delimiters: \verb`$ $`. A command \verb`\eval{ }` is wrapped around these, and two square-bracketed optional arguments have been appended. In the first option numerical values are assigned to the quantities \verb`m` and \verb`c` occurring in the formula. The assignments are separated by a comma since the dot is being used as the decimal point in this document. The second option contains a cryptic specification of the format of the numerical result – to $8$ places of decimals, and in (proper) scientific notation – the \verb`x`. Running \texttt{pdflatex} on this document generates a pdf displaying \begin{centred} \eval{$ mc^2$}[m=70,c=299792458][8x] \end{centred} \noindent where the formula ($mc^{2})$ is equated to the numerical value resulting from substituting the given values of $m$ and $c$. Those values are displayed in a list following the result. As specified, the result of the calculation is presented to $8$ decimal places in scientific notation. (According to Einstein's famous equation $E=mc^{2}$ this is the enormous energy content, in joules, of what was once considered an average adult Caucasian male.)\footnote{\noindent In earlier versions of \texttt{numerica} this calculation evaluated incorrectly because spaces were used to make \texttt{c=299792458} more `eye friendly'. Although numbers with spaces can now be read by \texttt{numerica}, this ability needs to be turned on by the user. `Out of the box' it is off; see §\ref{subsec:evalNumbers}.} A second example is provided by the formula in earlier remarks: \begin{verbatim} \documentclass{article} \usepackage{numerica} \begin{document} \begin{quote} First, evaluate the expression when it sits between textstyle delimiters, \eval{\( \frac{\sin(3.5)}{2} + 2\cdot 10^{-3} \)}, and then, second, when it sits between displaystyle delimiters: \eval{\[ \frac{\sin(3.5)}{2} + 2\cdot 10^{-3} \]} \end{quote} \end{document} \end{verbatim} Running \texttt{pdflatex} on this document produces the result: \begin{quote} First, evaluate the expression when it sits between textstyle delimiters, \eval{\( \frac{\sin(3.5)}{2} + 2\cdot 10^{-3} \)}, and then, second, when it sits between displaystyle delimiters: \eval{\[ \frac{\sin(3.5)}{2} + 2\cdot 10^{-3} \]} \end{quote} (For a quick mental check of the result, note that $\sin(3.5)\approx-0.35$.) The \verb`\eval` command used in these examples is the main command of the \texttt{numerica} package and is discussed fully in the next two chapters, but I first discuss different ways to display the results of calculations. \subsection{Display of the result} \label{subsec:introResultDisplay}In what follows I shall write things like (but generally more complicated than) \begin{centred} \verb`$ \eval{ 1+1 } $` $\Longrightarrow \eval{ 1 + 1 } $ \end{centred} to mean: run \texttt{pdflatex} on a document containing \verb`$ \eval{ 1+1 } $` in the document body to generate a pdf containing the calculated result – $2$ in this instance, as indicated by the arrow. The reader will note that I have used dollar signs to delimit the math environment. I could (and perhaps should) have used the more \LaTeX -pure \verb`\( \)`, but habit has won out. In the example the \verb`\eval` command is used \emph{within} a math environment (delimited by the dollar signs). \begin{itemize} \item When the \verb`\eval` command is used\emph{ within} a math environment, only the \emph{numerical result,} followed possibly by the \emph{variable=value list}, is displayed (within the given math environment). \end{itemize} For the \emph{variable=value list} see the $mc^{2}$ example earlier where values were assigned to $m$ and $c$ in a trailing optional argument; this is discussed more fully in §\ref{sec:evalVv-list}. As a simple example, I repeat the previous addition with variables $x$ and $y$: \begin{centred} \verb`$ \eval{ x+y }[x=1,y=1] $` $\Longrightarrow$ $ \eval{ x+y }[x=1,y=1]$ \end{centred} (If the package option \verb`comma` were being used, setting the comma as the decimal point, then the example would look like \verb`$ \eval{ x+y }[x=1;y=1] $` with a semicolon separating the variable assignments.) To my eye, display of the variable=value list in this example looks silly. It needs context, some prior commentary or statement of the formula like \begin{centred} \verb`$ x+y=\eval{ x+y }[x=1,y=1] $` $\Longrightarrow$ $ x+y=\eval{ x+y }[x=1,y=1] $ \end{centred} Otherwise display of the variable=value list can be suppressed, most simply by appending a star (asterisk) to the \verb`\eval` command; see §\ref{subsec:evalVvSuppresList} or later in this section. Environments may include the standard \LaTeX{} inline (\verb`$ $` or \verb`\( \)` or \verb`math`) environments, the \verb`displaymath`, \verb`\[ \]` and \verb`equation` environments, the \verb`eqnarray` environment, as well as the AMS environments which come into their own when multi-formula calculations are performed, or when long formulas with many variables are involved (\verb`multline`). Examples will recur throughout this document. \verb`\eval` is not limited to use within a math environment. As we have already seen with the $mc^{2}$ example, it can also wrap \emph{around} math delimiters: \begin{centred} \verb`\eval{$ x+y $}[x=1,y=1]` $\Longrightarrow$ \eval{$ x+y $}[x=1,y=1] \end{centred} When it does, the display that results is different, as you can see. The formula is \emph{automatically} included in the display; it does not need to be written in `by hand' as I did in the previous example. \begin{itemize} \item When the \verb`\eval` command is wrapped\emph{ around} a math environment, the result is displayed within that environment in the form, \emph{formula=numerical result}, followed possibly by the \emph{variable=value list}. \begin{itemize} \item If the formula is long or contains many variables then it may be desirable to split the display over two lines; see the \verb`multline*` example below, and §\ref{subsec:evalChanging-display-format}. \end{itemize} \item An alternative to explicitly wrapping \verb`\eval` around math delimiters is to use the \emph{settings} option, an optional argument before the main (mandatory) argument, and enter \verb`env=` there, for example like this: \end{itemize} \begin{centred} \verb`\eval[env=$]{x+y}[x=1,y=1]` $\Longrightarrow$ \eval[env=$]{x+y}[x=1,y=1] \end{centred} which reproduces the previous display. Doing this is more convenient when more `verbose' environment names than the brief \verb`$ $`, \verb`\( \)` or \verb`\[ \]` are used (although you can write, say, \verb`\eval{\begin{multline*}...\end{multline*}}` if so inclined). Here is an example of a \verb`multline*` environment being used to `tame' the display of a long unwieldy formula (the phantom is there so that the hanging $+$ sign spaces correctly): \begin{verbatim} \eval[env=multline*] { 1+2+3+4+5+6+7+8+9+10+\phantom{0}\\ 11+12+13+14+15+16+17+18+19 } \end{verbatim} $\Longrightarrow$ \eval[env=multline*] { 1+2+3+4+5+6+7+8+9+10+\phantom{0} \\ 11+12+13+14+15+16+17+18+19 } \noindent Note how the phantom and the new line command \verb`\\` are swallowed by \verb`\eval` without complaint. \begin{itemize} \item It is also possible to dispense with math delimiters entirely, neither wrapped within the \verb`\eval` command nor wrapped around it nor invoked with the \verb`env` setting, in which case \texttt{numerica} displays the \emph{numerical result} between \verb`$` delimiters. \end{itemize} \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% This is different from the behaviour in earlier versions of \texttt{numerica} when no math delimiters were involved. Then, \verb`\[ \]` delimiters were wrapped around the \emph{numerical result}, possibly followed by the \emph{variable=value} list. Now only the \emph{numerical result} is displayed and, since the absence of the variable=value list means no mathematical constructs like \verb`\frac`-tions are present, inline delimiters seem more appropriate than the previously used \verb`\[ \]`.\end{shaded}% \end{minipage} \begin{verbatim} \begin{quote} The result of subtracting $e^\pi$ from $\pi^e$ is \eval{ \pi^e-e^\pi } which is negative; hence $e^\pi>\pi^e$. \end{quote} \end{verbatim} is an example of \verb`\eval` used in the absence of delimiters and produces the result: \begin{quote} The result of subtracting $e^\pi$ from $\pi^e$ is \eval{ \pi^e-e^\pi} which is negative; hence $e^\pi>\pi^e$. \end{quote} Note that the minus sign displays correctly because of the \verb`$` delimiters automatically inserted by \texttt{numerica}. \begin{itemize} \item What is displayed can be pared to the minimum by appending an asterisk to the \verb`\eval` command. Then, only the \emph{numerical result} is displayed, with no math delimters added; if \verb`\eval*` is used within a math environment, the numerical result will be displayed accordingly, but otherwise the result will be displayed as text, a negative sign displaying as a hyphen. \end{itemize} Compare \verb`\eval*{ \pi^e-e^\pi }` $\Longrightarrow$ \eval*{ \pi^e-e^\pi } with the previous example. In the present example only the numerical result is displayed – as text, with a hyphen depicting the minus sign. It is up to you, the user, to provide the surrounding math environment if you want a proper minus. \subsubsection{Punctuation: the \texttt{p} setting} \label{subsec:introPunctuation}To complete a display you may wish to add a punctuation mark – usually a comma or full stop – after the displayed expression. For inline use punctuation is easy: add the punctuation mark after the \verb`\eval` command and its arguments: \verb`\eval{$ 2\pi $},` $\Longrightarrow$ \eval{$ 2\pi $}, and \verb`$\eval{ 1+x+y }[x=2,y=3]$.` $\Longrightarrow$ $\eval{ 1+x+y }[x=2,y=3]$. The mark appears in the right place. For displaystyle environments punctuation is not so straightforward. When \verb`\eval` is used \emph{within} a displaystyle environment, say between \verb`\[` \verb`\]` delimiters, it is easy to add a comma or full stop after the \verb`\eval` command and its arguments but before the closing delimiter, \verb`\[ x+1=\eval{ x+1 }[x=1],\]` and the punctuation mark will appear in the right place. But when the \verb`\eval` command wraps \emph{around} \verb`\[ \]` delimiters or the \verb`env=\[` option is used, a problem arises: a fullstop or comma after the \verb`\eval` command and its arguments – \verb`\eval{\[ 1+1 \]}.` – lies \emph{beyond} the closing delimiter and will slide off to the start of the next line, \emph{after} the displayed result. We want it to display as if it were the last element \emph{before} the closing delimiter. Explicitly putting it there, like \verb`\eval{\[ 1+1.\]}`, means the punctuation mark becomes part of the formula. Potentially \texttt{numerica} then needs to check not just for a fullstop but also other punctuation marks like comma, semicolon, perhaps even exclamation and question marks. All these marks have roles in mathematics or \texttt{l3fp} or \texttt{numerica}, and the program\texttt{ }responds to them accordingly. For instance a full stop is also the decimal point mark and is treated as such (giving the rather cryptic result \verb`\eval{$ . $}` $\Longrightarrow$ \eval{$ .$} since the solitary dot is interpreted as the number $0.0$). An exclamation mark is the factorial sign; \texttt{numerica} recognizes it as such: \verb`\eval{$ 4! $}` $\Longrightarrow$ \eval{$ 4!$}. A comma is used to separate the arguments of $n$-ary functions like \verb`\max` and \verb`\min`: \verb`$\eval{\min(\pi,e,\phi,\gamma)}$` $\Longrightarrow$ $\eval{\min(\pi,e,\phi,\gamma)}$. And as we will see below, a semicolon is used by \texttt{numerica} to separate expressions in a multi-formula calculation. Distinguishing the punctuation role from the mathematical role of these marks would only complicate the code and slow evaluation. Instead, \texttt{numerica} uses a key in the settings option to add punctuation. As already noted, the settings option is an optional argument preceding the main argument, already met in relation to the \verb`env`-ironment key. A second setting is the punctuation key \verb`p`. Indeed, simply entering \verb`p`, as here, \begin{verbatim} \eval[p]{\[ 1+x+y+z+xy+yz+zx+xyz \]}[x=2,y=3,z=4] \end{verbatim} $\Longrightarrow$ \eval[p]{\[ 1+x+y+z+xy+yz+zx+xyz \]}[x=2,y=3,z=4]puts a comma in the correct place, after the closing parenthesis of the variable=value list. If a full stop is wanted use \verb`p=.`: \begin{verbatim} \eval[env=\[,p=.]{ (1+x)(1+y)(1+z) }[x=2,y=3,z=4] \end{verbatim} $\Longrightarrow$ \eval[p=.,env=\[ ]{ (1+x)(1+y)(1+z) }[x=2,y=3,z=4]Again the mark appears in the right place. As you can see, the settings option is a comma-separated list of \emph{key=value} pairs.\emph{ }This remains true of the settings option even when the \verb`comma` package option is used, since the only numbers appearing in the settings are integers – ambiguity does not arise. That entering \verb`p` alone sufficed is because the punctuation key \verb`p` defaults to a comma. If you want some other mark – a semicolon or exclamation mark perhaps – equate \verb`p` to that mark in the optional argument. The default value for \verb`p` does not change if the \verb`comma` package option is used. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% The comma is chosen as the default not only because it is a commonly used mark at the end of equations but because the settings option is a comma-separated list. By making the default the comma, it suffices to write \verb`p` when you want a comma – rather than the more awkward \verb`p={,}` which would otherwise be required.\end{shaded}% \end{minipage} \subsection{Multi-formula calculations} \label{subsec:introMult-formula-calculations}It is possible to evaluate more than one expression at a time in the one \verb`\eval` command by means of a further setting \verb`ff`, or \verb`ff=`. The default separator of one formula from the next is the same as that used in the variable=value list. If the decimal point is a dot, then the default separator is a comma; if the decimal point is a comma (with the \verb`comma` package option) then the default separator is a semicolon. In both cases this will generally be fine except when $n$-ary functions are involved since their arguments are delimited in the same way. Either one can wrap the arguments of these functions in braces or, better, choose a different separator by means of the setting \verb`ff=`. I give an example shortly below; also see §\ref{subsec:settingsMulti-formula-separator}. For this document the decimal point is a dot and the comma generally suffices. Suppose we want the values of the main trigonometric functions at, say, $\pi/6$. In the example, I have entered the functions separated by commas, assigned the value $\pi/6$ to the variable $x$ in the trailing optional argument and concluded the display with a full stop by means of the \verb`p=.` setting. The point to note is the \verb`ff` in the settings option, signalling a multi-formula calculation: \begin{verbatim} \eval[ff,p=.]{\[ \sin x, \cos x, \tan x \]}[x=\pi/6] \end{verbatim} $\Longrightarrow$ \eval[ff,p=.]{ \[ \sin x, \cos x, \tan x \] }[x=\pi/6]To understand these values we might add \begin{centred} \verb`\eval[ff,p=.]{\[ \surd3/2, 1/\surd3 \]}` $\Longrightarrow$ \eval[ff,p=.]{ \[\surd3/2, 1/\surd3 \]} \end{centred} The displays in both instances follow the default format for a multi-formula calculation in the \verb`equation*` (\verb`\[`) environment. There are irritants: the failure of the equals signs to line up, the repetition of the variable=value list, the different numbers of digits displayed in the answers and, if you are a `punctuator', you might like commas to terminate the intermediate rows. For back-of-envelope calculations, who cares? But for inclusion in more formal documents such things matter. All can be remedied: see §\ref{subsec:evalPadding-with-zeros} (and below) about padding numbers with zeros to a given number of decimal places; see §\ref{subsec:settingsEnvironmentSettings} about use of AMS environments to guarantee alignment; see §\ref{subsec:settingsEnvironments-=00005C=00007D} about suppressing repetition of the variable=value list. Punctuating the intermediate rows I discuss next. \subsubsection{Punctuation: the \texttt{pp} } \label{subsec:intoMultiFormulaPunctuation}Like the \verb`p` setting, there is a \verb`pp` setting also entered in the settings argument of the \verb`\eval` command that enables the insertion of punctuation at the end of intermediate results in a multi-formula calculation; the \verb`p` setting still determines the terminating punctuation mark. Like \verb`p`, \verb`pp` defaults to a comma, which means that you need enter only \verb`pp` to insert commas. This remains true if the \verb`comma` package option is used. For any other mark you need to equate \verb`pp` to that mark – e.g. \verb`pp=;`. Thus, repeating the first of the examples above, I've added \verb`pp` to the settings option, and also added a star (asterisk) in a second trailing argument on the right. This triggers padding the numerical result with zeros, should it not display the default six decimal places – as happens with both $\sin x$ and $\tan x$ (because they round to five or fewer figures). \begin{verbatim} \eval[ff,pp,p=.]{\[ \sin x, \cos x, \tan x \]}[x=\pi/6][*] \end{verbatim} $\Longrightarrow$ \eval[ff,pp,p=.]{\[ \sin x, \cos x, \tan x \]}[x=\pi/6][*] \noindent The display is improved: commas terminate intermediate rows, a full stop is at the end, and by padding with zeros, all three results display six decimal places and now align vertically. \subsubsection{Multi-formula separator: the \texttt{ff} setting} \noindent\label{subsec:introMultiFormulaSeparator}That the last example displays as desired depends on all three results being positive. If $x=5\pi/6$, $\cos x$ and $\tan x$ will be negative and minus signs will destroy the alignment. The secret then is to use an \verb`alignat*` environment. Also, just to show how it's done, I've changed the multi-formula separator with the setting \verb`ff=|`. (Even if a formula contained an absolute value it should not contain the \verb`|` character but rather \verb`\abs` or \verb`\lvert`, \verb`\rvert`; see §\ref{sec:calcAbsValueEtc}.) \begin{verbatim} \eval[pp,p=.,env=alignat*,ff=|] {\[ \sin x | \cos x | \tan x \]}[x=5\pi/6][*] \end{verbatim} $\Longrightarrow$ \eval[pp,p=.,env=alignat*,ff=|] {\[ \sin x | \cos x | \tan x \]}[x=5\pi/6][*] \noindent Padding wit zeros and the \verb`alignat*` environment have ensured alignment of the numerical results. Multi-formula calculations can also be performed in an inline context. In the following example, the \verb`p` setting has been dispensed with since a full stop can be inserted at the end `by hand' without problem. Again, just to show how, I have used the \verb`ff=` setting (although \verb`&` is a confusing character to use for anyone familiar with \LaTeX ): \begin{centred} \verb`$\eval[pp,ff=&]{ \pi & \pi/2 & 1/\pi & \surd\pi }$` $\Longrightarrow$ $\vsp\eval[pp,ff=&]{ \pi & \pi/2 & 1/\pi & \surd\pi }$. \end{centred} By default, a quad of space is inserted between results of a multi-formula calculation in an inline (\verb`$ $`, \verb`\( \)` or \verb`math`) context, as evident here. This can be changed by means of the \verb`sep` (for separator) setting (§\ref{subsec:settingsEnvironments-sep}). For more on environments and their tweaks, see §\ref{subsec:settingsEnvironmentSettings}. \subsection{Examples of use} To give a sense of how \texttt{numerica} can be used, I include some examples of actual use of the program. (The \texttt{numerica-plus} and \texttt{numerica-tables} packages contain others.) \subsubsection{Checking} Occasionally, just to reassure myself that age hasn't completely rotted my brain I like to tackle short mathematical problems I come across on the internet. One that caught my attention was to simplify $\sqrt{220-30\sqrt{35}}$. After some bumbling and fumbling, I let \[ x=\sqrt{220-30\sqrt{35}},\qquad y=\sqrt{220+30\sqrt{35}}, \] (which seems an obvious thing to do) so that \[ xy=10\sqrt{484-315}=10\sqrt{169}=10\sqrt{13^{2}}=130. \] Since $x^{2}+y^{2}=440$ it was easy to form both $(x+y)^{2}$ and $(x-y)^{2}$, and by separating the resulting numbers into their prime factors, to find $y+x$ and $y-x$ and work out that $x=5\sqrt{7}-3\sqrt{5}$. Was I right, or had I made a mistake? Since \begin{verbatim} \eval[p,pp,ff]{\[\sqrt{220-30\sqrt{35}}, 5\sqrt{7}-3\sqrt{5}\]} \end{verbatim} $\Longrightarrow$ \eval[p=.,pp,ff]{\[ \sqrt{220-30\sqrt{35}}, 5\sqrt{7}-3\sqrt{5} \]} \noindent the simplification was correct. Indeed $y=5\sqrt{7}+3\sqrt{5}$: \begin{verbatim} \eval[p=.,pp,ff]{\[\sqrt{220+30\sqrt{35}}, 5\sqrt{7}+3\sqrt{5}\]} \end{verbatim} $\Longrightarrow$ \eval[p=.,pp,ff]{\[ \sqrt{220+30\sqrt{35}}, 5\sqrt{7}+3\sqrt{5} \]} \noindent As a final flourish, \begin{verbatim} \eval{$xy$}[x=5\sqrt{7}-3\sqrt{5}, y=5\sqrt{7}+3\sqrt{5}] \end{verbatim} $\Longrightarrow$ \eval{$ xy $} [x=5\sqrt{7}-3\sqrt{5}, y=5\sqrt{7}+3\sqrt{5}]. \subsubsection{Exploring } \label{subsec:introExploring}When working on \texttt{numerica}'s predecessor package, I constantly tested it against known results to check for coding errors. One test was to ensure that \[ \left(1+\frac{1}{n}\right)^{n} \] did indeed converge to the number $e$ as $n$ increased.\texttt{ }Let's do that here. Try first $n=10$: \begin{center} \verb`\eval{$ e-(1+1/n)^n $}[n=10][x]` $\Longrightarrow$ \eval{$ e-(1+1/n)^n $}[n=10][x]. \par\end{center} \noindent (The default number of decimal places displayed is $6$.) The difference between $e$ and $(1+1/n)^{n}$ is about an eighth ($0.125$) when $n=10$, which is encouraging but hardly decisive. The obvious thing to do is increase the value of $n$. I'll use an \verb`align*` environment to `prettify' the presentation of the results. Although looking like a solid block of typing, most of the following was done by copy-and-paste; I only had to change the exponent on the \verb`10`: \begin{verbatim} \begin{align*} e-(1+1/n)^{n} &= \eval{e-(1+1/n)^n}[n=1\times10^5][*x],\\ e-(1+1/n)^{n} &= \eval{e-(1+1/n)^n}[n=1\times10^6][*x],\\ e-(1+1/n)^{n} &= \eval{e-(1+1/n)^n}[n=1\times10^7][*x],\\ e-(1+1/n)^{n} &= \eval{e-(1+1/n)^n}[n=1\times10^8][*x]. \end{align*} \end{verbatim} This gave the result \begin{align*} e-(1+1/n)^{n} & =\eval{e-(1+1/n)^{n}}[n=1\times10^{5}][x],\\ e-(1+1/n)^{n} & =\eval{e-(1+1/n)^{n}}[n=1\times10^{6}][*x],\\ e-(1+1/n)^{n} & =\eval{e-(1+1/n)^{n}}[n=1\times10^{7}][x],\\ e-(1+1/n)^{n} & =\eval{e-(1+1/n)^{n}}[n=1\times10^{8}][x]. \end{align*} Clearly $(1+1/n)^{n}$ converges to $e$, the difference between them being of order $1/n$, but that is not what catches the eye. There is an unanticipated regularity here. 1.35914? Double the number: \verb`\eval{2\times 1.35914}[5]` $\Longrightarrow$ \eval{2\times 1.35914}[5] which looked like $e$ to me and suggested a relationship, namely, \[ \lim_{n\to\infty}n\left(e-\left(1+\frac{1}{n}\right)^{n}\right)=\tfrac{1}{2}e. \] \noindent I hadn't seen this before. Is it true? Since \[ \ln\left(1+\frac{1}{n}\right)^{n}=n\ln\left(1+\frac{1}{n}\right), \] it followed from the familiar expansion of the logarithm that \begin{align*} \ln\left(1+\frac{1}{n}\right)^{n} & =n\left(\frac{1}{n}-\frac{1}{2}\frac{1}{n^{2}}+\frac{1}{3}\frac{1}{n^{3}}-\ldots\right)\\ & =1-\frac{1}{2n}\left(1-\frac{2}{3}\frac{1}{n}+\frac{2}{4}\frac{1}{n^{2}}-\right). \end{align*} Write $E_{n}$ for the bracketed series on the right. $E_{n}$ is an alternating series and the magnitudes of the terms of the series tend to $0$ monotonically. Hence $1>E_{n}>1-2/3n$ and $E_{n}\to1$ as $n\to\infty$. Now exponentiate: \[ \left(1+\frac{1}{n}\right)^{n}=e\times e^{-E_{n}/2n}, \] so that \[ n\left(e-\left(1+\frac{1}{n}\right)^{n}\right)=ne\Big(1-e^{-E_{n}/2n}\Bigr). \] The proposed limit, new to me, now followed from the standard inequality (see \emph{HMF }2.3.32), $x/(1+x)<1-e^{-x}-1$. \subsubsection{Reassuring} \label{subsec:introReassurance}In the course of some hobbyist investigations in plane hyperbolic geometry I derived the formula \[ \Phi_{1}(m,n)=\cos\tfrac{m}{n}\pi-(1-4\sin^{2}\tfrac{m}{3n}\pi)\frac{\sin\tfrac{1}{n}\pi\sin\tfrac{m-1}{n}\pi}{2\sin^{2}\tfrac{m}{3n}\pi}, \] for $m=2,3,\ldots$ and integral $n\ge2m+1$. A key concern was: when is $\Phi_{1}$ positive? $\Phi_{1}$ itself was opaque; could I work it into an equivalent but more enlightening form? After an embarrassingly laborious struggle, I derived the expression \[ \Phi_{2}(m,n)=\left(\frac{1-4\sin^{2}\tfrac{m}{3n}\pi}{2\sin^{2}\tfrac{m}{3n}\pi}\right)\sin\tfrac{2m-3}{3n}\pi\sin\tfrac{m-3}{3n}\pi, \] in which the conditions for positivity were now clear: with $n\ge2m+1$, so that $m\pi/3n<\pi/6$, the first parenthesized factor is always positive; the second is positive for $m\ge2$, and the third is positive for $m\ge4$. All well and good, but given the struggle to derive $\Phi_{2}$, was I confident that $\Phi_{1}$ and $\Phi_{2}$ really\emph{ }are equal? It felt all too likely that I had made a mistake. The simplest way to check was to see if the two expressions gave the same numerical answers for a number of $m,\thinspace n$ values. First I checked for $m=2,n=5$: I wrote \verb`\eval{\[ \]}[m=2,n=5]` twice and between the delimiters pasted the already composed expressions for $\Phi_{1}$ and $\Phi_{2}$, namely: \begin{verbatim} \eval{\[ \cos\tfrac{m}{n}\pi-(1-4\sin^{2}\tfrac{m}{3n}\pi) \frac{\sin\tfrac{1}{n}\pi\sin\tfrac{m-1}{n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} \]}[m=2,n=5] \eval{\[ \left( \frac{1-4\sin^{2}\tfrac{m}{3n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} \right) \sin\tfrac{2m-3}{3n}\pi\sin\tfrac{m-3}{3n}\pi \]}[m=2,n=5] \end{verbatim} I have added some formatting – indenting, line breaks – to make the formulas more readable but otherwise left them unaltered. The \verb`\eval` command can be used for even quite complicated expressions without needing to tinker with their \LaTeX{} form, but you may wish – as here – to adjust white space to clarify their component parts. Running \texttt{pdflatex} on these expressions, the results were \eval{\[ \cos\tfrac{m}{n}\pi-(1-4\sin^{2}\tfrac{m}{3n}\pi) \frac{\sin\tfrac{1}{n}\pi\sin\tfrac{m-1}{n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} \]}[m=2,n=5] \eval{\[ \left( \frac{1-4\sin^{2}\tfrac{m}{3n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} \right) \sin\tfrac{2m-3}{3n}\pi\sin\tfrac{m-3}{3n}\pi \]}[m=2,n=5] \noindent which was reassuring. (The result is negative since $m-3<0$.) I could have avoided the double writing of \verb`\eval` and \verb`[m=2,n=5]` by putting a comma between the expressions and performing a multi-formula calculation. This time I've checked equality for \verb`m=5` and \verb`n=13`, which should give a positive result, and I've taken the opportunity to \verb`align*` the results with the \verb`env` setting: \begin{verbatim} \eval[p=.,pp,env=align*,ff] { \cos\tfrac{m}{n}\pi-(1-4\sin^{2}\tfrac{m}{3n}\pi) \frac{\sin\tfrac{1}{n}\pi\sin\tfrac{m-1}{n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} , \left( \frac{1-4\sin^{2}\tfrac{m}{3n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} \right) \sin\tfrac{2m-3}{3n}\pi\sin\tfrac{m-3}{3n}\pi }[m=5,n=13] \end{verbatim} which evaluates to \eval[p=.,pp,env=align*,ff]{ \cos\tfrac{m}{n}\pi-(1-4\sin^{2}\tfrac{m}{3n}\pi) \frac{\sin\tfrac{1}{n}\pi\sin\tfrac{m-1}{n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} , \left( \frac{1-4\sin^{2}\tfrac{m}{3n}\pi} {2\sin^{2}\tfrac{m}{3n}\pi} \right) \sin\tfrac{2m-3}{3n}\pi\sin\tfrac{m-3}{3n}\pi }[m=5,n=13] \noindent Thus reassured that there was \emph{not }an error in my laborious derivation of $\Phi_{2}$ from $\Phi_{1}$, it was not difficult to work back from $\Phi_{2}$ to $\Phi_{1}$ then reverse the argument to find a straightforward derivation. \chapter{\texttt{\textbackslash nmcEvaluate} (\texttt{\textbackslash eval)}} \label{chap:evalEvaluate}The main calculational command in \texttt{numerica} is \verb`\nmcEvaluate`. Because this would be tiresome to write too frequently,\texttt{ }particularly for back-of-envelope calculations, there is an equivalent short-name form, \verb`\eval`, used almost exclusively in this document. But wherever you see \verb`\eval` you can substitute \verb`\nmcEvaluate` and obtain the same result. \verb`\eval` is defined using \verb`\ProvideDocumentCommand` from the \texttt{xparse} package. Hence if already defined in some other package already loaded, it will not be redefined by \texttt{numerica}. It will retain its meaning in the other package. Its consequent absence from \texttt{numerica} may be an irritant, but only that. \verb`\nmcEvaluate` is unlikely to be defined elsewhere and should still be available. \section{Syntax of \texttt{\textbackslash nmcEvaluate (\textbackslash eval)}} \verb`\nmcEvaluate` (or \verb`\eval`) takes five arguments of which only the third is mandatory. All others are optional. If all are deployed the command looks like \begin{centred} \noindent\verb`\nmcEvaluate*[settings]{expr.}[vv-list][num. format]` \end{centred} I discuss the various arguments in the referenced sections. \begin{enumerate} \item \verb`*` optional \emph{number-only} switch; if present ensures display of only the numerical result, as text with no formatting; see §\ref{subsec:evalVvSuppresList}; \item \verb`[settings]` optional comma-list of \emph{key=value settings} of the calculational environment for this particular calculation; see §\ref{chap:settingsSettings}; \item \verb`{expr.}` mandatory main argument, the mathematical \emph{expression} in \LaTeX{} form that is to be evaluated, or a list of such expressions; see §\ref{subsec:evalExpressions}; \item \verb`[vv-list]` optional list of \emph{variable=value }entries; see §\ref{sec:evalVv-list}; \item \verb`[num. format]` optional \emph{number-format} specification for the numerical result (rounding, padding with zeros, scientific notation, boolean or fraction-form output); see~§\ref{sec:evalRoundingEtc}. \end{enumerate} Note that arguments 4 and 5 are both square-bracket delimited optional arguments. Should only one such argument be used, \texttt{numerica} determines which is intended by looking for an equals sign within the argument. Its presence indicates the argument is the vv-list; its absence indicates the argument is the number-format specification. The vv-list and number-format specification are trailing optional arguments but do not need to be hard against their preceding arguments; intervening spaces are allowed. This means there is a possibility that should the \verb`\eval` command be followed by a square-bracketed mathematical expression that expression might be interpreted as a trailing argument. Experience using \texttt{numerica} suggests that this will be a (very) rare occurrence and is easily prevented by inserting an intervening empty brace pair (\verb`{}`). By allowing spaces between the arguments complicated expressions and large vv-lists can be formatted, in the interests of clarity, with new lines and white space without requiring the insertion of line-ending comment characters (\verb`%`). Recommended practice is to minimise the number of optional arguments used in \LaTeX{} commands by consolidating them into a single \emph{key=value} list. Although \texttt{numerica} uses such an argument (the settings optional argument), the vv-list does not fit naturally into that scheme. And practice suggests that separating out the elements of the number-format specification of the result and placing them in a trailing argument is both convenient and intuitive for the kind of back-of-envelope calculations envisaged for \texttt{numerica}. \subsection{Expressions} \label{subsec:evalExpressions}What kind of formula or expression can be `digested' by \verb`\nmcEvaluate`? As seen above (§\ref{subsec:introBasicProcedure}), a formula can be complicated, including components like $2\sin^{2}\tfrac{m}{3n}\pi$ or \[ \left(\frac{1-4\sin^{2}\tfrac{m}{3n}\pi}{2\sin^{2}\tfrac{m}{3n}\pi}\right), \] but the underlying aim is always: if the meaning of a formula in the \texttt{pdf} is clear to a human reader, it ought to be clear to \texttt{numerica}. In a perhaps surprising number of cases this aim can be met. Mathematicians understand an expression like $\sin2\pi x$ to mean the sine of the triple product $2\pi x$; so does \texttt{numerica}. Mathematicians casually use and understand logically wrong but customary notations like $\sin^{2}x$, the square of the sine of $x$; \texttt{numerica} digests this without fuss. Mathematicians use a wide variety of formatting commands to clarify their intent: \verb`\left` and \verb`\right`, \verb`\phantom`-s, spaces and new lines (\verb`\quad`, \verb`\\`), structural commands like \verb`\mathstrut`, or environments like \verb`align` or \verb`multline`; all are grist to \texttt{numerica}'s mill. \subsubsection{Multi-formula expressions} \label{subsec:evalMulti-formula-expressions}From version 3.0.0 of \texttt{numerica} the main (and only mandatory) argument of the \verb`\eval` command may contain more than one formula to be evaluated. `Expression' can now mean a (generally short) list of formulas. The default punctuation mark separating one formula from the next in the list is the same as that used in the vv-list – a comma if the decimal point is a dot, a semicolon if the decimal point is a comma. The only potential conflict is if a formula contains an $n$-ary function (\verb`\max` or \verb`\min` or \verb`\gcd`), since their arguments are separated by the same separators in the two cases. There are two responses. One is to wrap the $n$-ary function in braces. The other is to specify a different multi-formula delimiter in the settings option. This is done by entering \verb`ff=` there (see §\ref{subsec:settingsMulti-formula-separator}), where \verb`` is some suitably `neutral' character not otherwise present in any of the formulas to be evaluated – perhaps \verb`@`, or \verb`|`. Examples of multi-formula expressions being evaluated within the one \verb`\eval` command were seen earlier in the Introduction, especially at §\ref{subsec:introMult-formula-calculations}, and §\ref{subsec:introReassurance}. A multi-formula calculation is a natural way to check identities – see for example the test of $\sinh3x=3\sinh x+4\sinh^{3}x$ in §\ref{subsec:calcSquaring-etc-unary}. Numerous other examples occur throughout this document. \subsubsection{\protect\LaTeX{} braces and mathematical arguments} \label{subsec:evalBraced-groups}There are mathematical braces, \verb`\{ \}`, which display in the \texttt{pdf} and are used to delimit (generally larger) parts of mathematical expressions, and there are \LaTeX{} braces, \verb`{ }`, which do not display in the \texttt{pdf} and are used to delimit \LaTeX{} arguments or groupings. This discussion is about \LaTeX{} braces. Generally, the \LaTeX{} braces \verb`\eval` encounters should be `announced' by a preceding \LaTeX{} command. Thus the braced argument in \verb`\sqrt{x^2+1}`, displaying in a math environment as $\sqrt{x^{2}+1}$, is `announced' by the square root command. Similarly, \verb`\frac` and \verb`\binom` each announce two braced arguments. The superscripting \verb`^` or subscripting \verb`_` also announce a braced argument (in general). In these cases \verb`\eval` knows what to do with the braced argument because it is prepared by the preceding command. Although there is no \LaTeX{} requirement for them, braced arguments can also be used after unary functions like \verb`\sin` or \verb`\ln` or \verb`\tanh`. Given the presence of the unary function, \verb`\eval` knows what to do with an immediately following braced argument and will happily digest it – it has been announced by the unary function. Indeed, from version 3.0.0 of \texttt{numerica} this is the recommended way of handling (for instance) the more complicated arguments that frequently occur following \verb`\sin` and \verb`\cos` in the study of Fourier series; see §\ref{subsec:calcComplicated-arguments}. Even \emph{without} braces, \verb`\eval` will happily digest an argument to a unary function that is the product of a number, a variable, a constant, a \verb`\tfrac` (or an \verb`\sfrac` if \texttt{xfrac} is loaded) or some subset thereof: \begin{centred} \verb`\eval{$ \cos \tfrac1{12}2n\pi $}[n=2]` $\Longrightarrow$ \eval{$ \cos \tfrac1{12}2n\pi $}[n=2]. \end{centred} \LaTeX{} braces are for those situations where the reader sees the function's argument extending \emph{beyond} the point where a programming rule would end the argument. For example, a reader knows that the argument of the sine in $\sin\tfrac{1}{2}(A+B)$ does not end with the $\tfrac{1}{2}$, nor with the right parenthesis in $\sin(n+\tfrac{1}{2})\pi$ nor with the first factor in $\sin(n+\tfrac{1}{2})(x-t)$. It is for situations like this that em-bracing the argument is recommended. It makes no difference to the visual appearance, hence does not interfere with the reader's comprehension, but informs \texttt{numerica} of exactly where the argument ends. Because they are invisible in the \texttt{pdf}, \LaTeX{} braces should never be used to shorten what the reader sees as the argument of a function. \verb`\eval` assumes that the braced part is the \emph{whole} argument but the reader doesn't read that. For example, presented with \verb`\sin{2n}\pi`, \verb`\eval` assumes the sine's argument is $2n$ and does not extend to \verb`\pi`. This is not what a human reads in the \texttt{pdf}. The compiled expression, $\sin2n\pi$, is read as `the sine of $2n\pi$'. If the intention really is to multiply $\pi$ by $\sin2n$ then the reader needs to \emph{see }that this is so: $(\sin2n)\pi$ perhaps or $\sin2n\times\pi$ or, best, $\pi\sin2n$, but \emph{not} by means of \LaTeX{} braces which leave no visual trace in the \texttt{pdf}. \subsubsection{Unannounced braces} \emph{Unannounced} braced expressions should be used with care. When \verb`\eval` meets an unnanounced brace group it is `flying blind'. \LaTeX{} braces are `punctuation marks' for \LaTeX{} code, not for mathematical formulas. How could they be, since they do not display in the \texttt{pdf}? For \texttt{numerica} it is \emph{how things look in the }\texttt{\emph{pdf}} that is the guide. \verb`\eval` converts an unannounced braced expression into its corresponding \texttt{l3fp} form and appends that to the overall expression that is to be evaluated. It does not do anything further. Note in particular that it does not first evaluate the braced expression and append the result to the overall expression, nor does it parenthesize the \texttt{l3fp} form of the braced expression, nor does it check to see if a multiplying asterisk \verb`*` should be appended or prepended to the \texttt{l3fp} form. It simply converts the braced expression into its \texttt{l3fp} form and appends. This works fine if, as suggested above, the braces surround a function like \verb`\max(x,y,z)` so it can be included in a multi-formula calculation, but it can give unexpected results in other contexts. Thus (math braces; \LaTeX{} braces), \begin{centred} \verb`\eval[ff]{\[ \{ 1+2 \}^2, { 1+2 }^2 \]}` $\Longrightarrow$ \eval[ff]{\[ \{ 1+2 \}^2, { 1+2 }^2 \]} \end{centred} In the first of these \verb`eval` reads the math-braced expression, converts it into its \texttt{l3fp} form and appends that, which \emph{includes the math braces}, to the (empty at this stage) overall expression\emph{. }In the second of these, \verb`\eval` reads the braced expression, converts that to its \texttt{l3fp} form and appends the result to the (empty at this stage) overall expression. In both cases, \verb`\eval` proceeds to read and append \verb`^2` to the overall expression so that the superscript acts on a bracketed expression in the first case and on $2$ alone in the second. A second example is \begin{centred} \verb`\eval[ff]{\[ 3\{ 2+1 \}, 3{ 2+1 } \]}` $\Longrightarrow$ \eval[ff]{\[ 3\{ 2+1 \} , 3{ 2+1 } \]} \end{centred} Similarly \verb`{ 2+1 }\tfrac13` displays like $2+1\tfrac{1}{3}$ which one might naively expect to evaluate to $3.333333$ but in fact it evaluates to $2.333333$ since \texttt{l3fp} uses juxtaposition to mean \emph{multiply}. Because \LaTeX{} braces do not visibly display, this kind of result is all too likely. Unless there is some compelling reason to do otherwise avoid \emph{unannounced} brace groups in expressions except to `hide' functions containing problematic characters (like the argument separator in $n$-ary functions in some contexts). \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% There is also a quirk (or feature) of \texttt{l3fp} that could catch one out. An expression of the form \verb`(1)1` produces a \LaTeX{} error when \texttt{l3fp} tries to evaluate it. In \texttt{l3fp} a number can be placed directly \emph{before} a parenthesized expression but not after; \verb`1(1)` and \verb`(1)1` are read very differently by the program. In normal use, `behind the scenes' \texttt{numerica} takes care of this quirk; a user should never have to worry about it. But this internal coping mechanism is not activated when the \texttt{l3fp} form of a braced group is appended to the overall expression.\end{shaded}% \end{minipage} \subsection{Numbers} \label{subsec:evalNumbers}In the present document the numerous examples presented mainly use ordinary decimal notation for numbers, but scientific notation is also available, both for input (see §\ref{subsec:settingsInputtingSciNotation}) and output (see §\ref{subsec:evalScientificNotation}). \subsubsection{Decimal point} Prior to version 3.0.0 the only decimal marker accepted was the dot (period, full stop). Now, by means of the \verb`comma` package option, the comma can also be used as the decimal point. This means using semicolons in the variable=value list (see below §\ref{sec:evalVv-list}) and for separating the arguments of $n$-ary functions (§\ref{sec:calc-n-ary-functions}) in line with ISO 80000 Part 2, section 3 which reads: `A comma, semicolon or other appropriate symbol can be used as a separator between numbers or expressions. The comma is generally preferred, except when numbers with a decimal comma are used.' When the \verb`comma` package option is used, \texttt{numerica} \emph{insists} on semicolons for separating items in the two contexts mentioned. \subsubsection{Grouping blocks of digits} Sometimes, to make numbers more readable, blocks of digits are grouped together, separated perhaps by spaces or by an explicit mark like a comma. \texttt{numerica} can digest numbers in which the grouping is by \emph{spaces}, but not a mark. `Out of the box', however, the package does not expect spaces in numbers. This needs to be turned on by the user by entering \verb`1s2` (or \verb`1s2=1`; \verb`1s2` indicating a space `s' between digits) in the settings option: \begin{centred} \verb`\eval[1s2]{ 12 345.678 901 }` $\Longrightarrow$ \eval[1s2]{ 12 345.678 901} \end{centred} \texttt{l3fp} works to $16$ significant figures; so does \texttt{numerica}. But experience suggests that in `everyday' use significantly fewer digits are generally used, both as input and output. The cases in which grouping digits aids readability will be rare. For this reason, `out of the box', \verb`1s2=0`. Note that \verb`1s2=0` should not cause a \LaTeX{} error nor raise a message in \texttt{numerica} if a number containing spaces\emph{ }is fed to \verb`\eval`, but the result may be disconcerting: \begin{centred} \verb`\eval[1s2=0]{ 12 34 }` $\Longrightarrow$ \eval[1s2=0]{ 12 34 } \end{centred} What has happened in the example is that $12$ and $34$ have been read separately as distinct numbers, an asterisk inserted between them, and multiplied. Sometimes the product may lead to a result sufficiently close to the expected one as to pass unnoticed. For this reason it is recommended that spaces in numbers be avoided as a matter of habit except in rare special circumstances (e.g.\ when entering a number like \verb`0.7777 7777 7777 7777`). Grouping blocks of digits with spaces is available through the \verb`1s2` setting solely for \emph{inputting} numbers in the variable=value list or formula. The \verb`\eval` command does not \emph{output} numbers in this form. \subsection{Variable names} \label{subsec:evalVariableNames}In mathematical practice, variable names are generally single letters of the Roman or Greek alphabets, or occasionally from other alphabets, in a variety of fonts, and often with subscripts or primes or other decorations: $x,\,\boldsymbol{x},\,\mu,\,x',\,\alpha'',$ $\,T^{iv},\,\Theta_{n},\,\boldsymbol{a}'_{n},\,\beta''_{mn},\,\vec{v},\,k^{+},\,k_{-}$ are examples. \texttt{numerica} does not attempt to characterize variables by their `internals'(alphabet, font, decoration, etc.). Rather, the program accepts as a variable \emph{whatever lies to the left of the equals sign }in an item of the variable=value list (for which see §\ref{sec:evalVv-list} immediately below). What lies to the left is a \emph{\LaTeX{} expression}. Different \LaTeX{} almost always means different variable. For instance $x$ and x are \emph{different} variables since, in the underlying \LaTeX , one is \verb`x` and the other \verb`\mathrm{x}`. I write `\emph{almost} always' because there are exceptions. Since braces do not display in the \texttt{pdf}, names that look identical in the \texttt{pdf} may well be distinct in \LaTeX . This is true particularly of superscripts and subscripts: \verb`x_0` and \verb`x_{0}` appear identical in the \texttt{pdf} but in the underlying \LaTeX{} they are distinct, and will be treated as distinct variables by \texttt{numerica}. The user needs to be aware of this. Also, because equals signs and commas give structure to the variable=value list, a variable name should not contain a \emph{naked} equals sign or a \emph{naked} comma. Instead they should be decently wrapped in braces, like \verb`R_{=}` displaying as $R_{=}$. These provisos aside, variables can be single- or multi-token, can be in different fonts, can be decorated with primes and indices – and may even contain spaces. (But please don’t; such names are not part of mathematical practice.) If a variable is natural to the mathematical context, it will almost certainly be accepted as a variable in \texttt{numerica}. For the kind of back-of-envelope calculations envisaged for the package, most variables will be single letters from the Roman or Greek alphabets. \subsubsection{Multi-token variable handling} Although multi-token variables are perfectly acceptable, \emph{internally} \texttt{numerica} works with single tokens. Variable names can be so different in structure, one from another, that to ease the parsing of formulas, all \emph{internal} variable names are assumed to be single tokens. Hence a necessary initial step for the package is to map all multi-token variable names in the vv-list and the formula to single tokens. \texttt{numerica} does this by turning the multi-token variable names into control sequences with names in the sequence \verb`\nmc_a`, \verb`\nmc_b`, \verb`\nmc_c`, etc., then searches through the vv-list and the formula for every occurrence of the multi-token names and replaces them with the relevant control sequences. It does this in order of decreasing size of name, working from the names that contain most tokens down to names containing only two tokens. (Doing the replacing in this order prevents \emph{parts} of longer names possibly being mistaken for shorter variable names.) The conversion process uses computer resources. Even if there are no multi-token variables present, \texttt{numerica} still needs to check that this is so – unless the user alerts the program to the fact with the setting \verb`xx=0`; see §\ref{subsec:settingsMultitokSwitch}. \section{The variable=value list} \label{sec:evalVv-list}To evaluate algebraic, trigonometric and other formulas that involve variables we need to give those variables values. This is done in the \emph{variable=value list} – or \emph{vv-list} for short. This is the fourth argument of the \texttt{\textbackslash nmcEvaluate} command and is a square-bracket delimited optional argument (optional because an expression may depend only on constants and numbers). A vv-list is a comma-separated list (or, if the \verb`comma` package option is used, semicolon-separated list) where each item is of the form \emph{variable=value}. It might be something simple like \verb`[g=9.81,t=2]` or something more complicated like \begin{verbatim} [V_S=\tfrac43\pi r^3,V_C=2\pi r^2h,h=3/2,r=2]. \end{verbatim} Spaces around the equals signs or the commas (resp., semicolons) are stripped away during processing so that \verb`[g=9.81,t=2]` and \verb`[ g = 9.81 , t = 2 ]` are the \emph{same} variable=value list. \emph{Math delimiters should never be used in the vv-list. }If they are present they will cause errors. Math delimiters have a part to play only in the main argument, where their presence or absence can determine the form of display of the result, as discussed above in §\ref{subsec:introResultDisplay}. \subsection{Evaluation from right to left} In these examples, with variables depending on other variables, there is an implication: that the list is evaluated \emph{from the right}. Recall how a function of a function is evaluated, say\emph{ }$y=f(g(h(x)))$. To evaluate $y$, first $x$ is assigned a value then $h(x)$ is calculated, then $g(h(x))$ then $f(g(h(x)))=y$. We work from right to left, from the innermost to the outermost element. Or consider an example like calculating the area of a triangle by means of the formula \[ A=\sqrt{s(s-a)(s-b)(s-c)}. \] First we write the formula; then we state how $s$ depends on $a,b,c$, namely $s=\frac{1}{2}(a+b+c)$, then we give values to $a,b,c$. In \texttt{numerica} this is mirrored in the layout of the \verb`\eval` command: \begin{verbatim} \eval{$ \sqrt{s(s-a)(s-b)(s-c)} $} [s=\tfrac12(a+b+c),a=3,b=4,c=5] \end{verbatim} The formula in a sense is the leftmost extension of the vv-list. The entire evaluation occurs from right to left. This means that the rightmost variable in the vv-list can depend only on constants and numbers – although it may be a complicated expression of those elements. Other variables in the vv-list can depend on variables \emph{to their right} but not to their left. \subsection{Constants} \label{subsec:evalBuilt-in-Constants}\texttt{numerica} has five built-in constants and can also accept user-defined constants. For the latter, see §\ref{sec:supplConstants}. The five built-in constants known to \texttt{numerica} are \verb`\pi`, the ratio of circumference to diameter of a circle; \verb`e`, the base of natural logarithms; Euler's constant \verb`\gamma`, the limit of $\left(\sum_{1}^{N}1/n\right)-\ln N$ as $N\to\infty$; the golden ratio \verb`\phi`, equal to $\tfrac{1}{2}(1+\surd5)$; and the utilitarian constant \verb`\deg`, the size of a degree in radians. Using a comma list for a multi-formula calculation and an \verb`align*` environment, \begin{centred} \verb`\eval[env=align*,pp,p,ff]{ \pi, e, \gamma, \phi, \deg }` $\Longrightarrow$ \eval[env=align*,pp,p,ff]{ \pi, e, \gamma, \phi, \deg } \end{centred} \noindent so that \verb`\eval{$ 180\deg $}` $\Longrightarrow$ \eval{$ 180\deg $} (as it should). In some contexts it may feel natural to use any or all of \verb`\pi`, \verb`e`, \verb`\gamma` and \verb`\phi` as variables by assigning values to them in the vv-list. \texttt{numerica} does not object. The values assigned in this way override the built-in constant values. For example, if instead of the usual ABC we label a triangle EFG with sides (note!) $e=3,f=4$ and $g=5$, its area is\medskip{} \begin{verbatim} \eval{$ \sqrt{s(s-e)(s-f)(s-g)} $} [s=\tfrac12(e+f+g),e=3,f=4,g=5] \end{verbatim} $\Longrightarrow$ \eval{$ \sqrt{s(s-e)(s-f)(s-g)} $} [s=\tfrac12(e+f+g),e=3,f=4,g=5].\medskip{} \noindent Clearly the value $3$ assigned to \verb`e` in the vv-list has been used in the calculation, not the value of the constant. But if \verb`e` (or \verb`\pi` or \verb`\gamma` or \verb`\phi`) is not assigned a value in the vv-list then it has, by default, the value of the constant. In the case of \verb`e`, if you wish to use it as a variable, the constant is always available as \verb`\exp(1)`. No similar alternative is available for \verb`\pi`, \verb`\gamma` or \verb`\phi`. \subsection{Expressions in the variable=value list} Suppose our expression is $\tfrac{4}{3}\pi r^{3}$, the volume $V_{S}$ of a sphere in terms of its radius $r$, and we want to calculate the volume for different values of $r$ to get a sense of how rapidly volume increases with radius. \begin{centred} \verb`$ V_S=\eval{ \tfrac43\pi r^3 }[r=1] $` $\Longrightarrow$ $ V_S=\eval{ \tfrac43\pi r^3 }[r=1] $. \end{centred} Having set up this calculation it is now an easy matter to change the value of $r$ in the vv-list: \begin{centred} \verb`$ V_S=\eval{ \tfrac43\pi r^3 }[r=1.5] $` $\Longrightarrow$ $\vsp V_S= \eval{ \tfrac43\pi r^3 }[r=1.5] $. \end{centred} Or we could `rephrase' the calculation like this: \begin{centred} \verb`\eval{$ V_S $}[V_S=\tfrac43\pi r^3,r=2]` $\Longrightarrow$ $\vsp$\eval{$ V_S $}[V_S=\tfrac43\pi r^3,r=2]. \end{centred} As you can see, values in the vv-list are not limited to numbers. They can be expressions depending on constants, numbers or other variables to their right in the list. This calculation also shows a multi-token variable (\verb`V_S`) being used. Another example: to compute the volume $V_{C}=\pi r^{2}h$ of a cylinder, we have two variables to assign values to: \begin{centred} \verb`$ V_C=\eval{ \pi r^2h }[h=4/3,r=1] $` $\Longrightarrow$ $\vsp V_C=\eval{ \pi r^2h }[h=4/3,r=1] $. \end{centred} Or we can divide the calculation up like this, \begin{centred} \verb`$ V_C=\eval{ hA_C }[A_C=\pi r^2,h=4/3,r=1] $` $\Longrightarrow$ $\vsp V_C=\eval{ hA_C }[A_C=\pi r^2,h=4/3,r=1] $, \end{centred} which emphasizes that the volume is `base $\times$ height' (and again uses a multi-token variable). A third instance is provided by the example above in which we calculated the area of a triangle by means of Brahmagupta's formula. \subsection{Display of the vv-list} By default, the vv-list is displayed with the numerical result. That and the format of the display can both be changed. \subsubsection{Changing the display format} \label{subsec:evalChanging-display-format}In the example above where the area of a triangle is calculated using Brahmagupta's formula, display of the result is crowded. One remedy is to force display of the vv-list to a new line. In the default set-up, this happens automatically if the \verb`env` setting is equated to \verb`multline` or \verb`multline*`. Let's do this when Brahmagupta's formula is used not for a triangle but in the more challenging case of a cyclic quadrilateral. The cyclic quadrilateral in question is formed by a 45-45-90 triangle of hypotenuse 2 joined to a 30-60-90 triangle along its hypotenuse of the same length. Two triangles, six vertices but the two along the hypotenuses are shared, hence four vertices in all, lying on a circle. The sides of the cyclic quadrilateral are therefore $\surd2,\surd2,\surd3,1$. Adding the areas of the two triangles, the area of the quadrilateral is $A=1+\tfrac{1}{2}\surd3$, or in decimal form, \verb`$\eval{1+\tfrac12\surd3}$` $\Longrightarrow$ $\eval{1+\tfrac12\surd3}$. Let's check with Brahmagupta's formula: \begin{verbatim} \eval[env=multline*]{\sqrt{(s-a)(s-b)(s-c)(s-d)}} [s=\tfrac12(a+b+c+d), a=\surd2,b=\surd2,c=\surd3,d=1] \end{verbatim} $\Longrightarrow$ \eval[env=multline*]{ \sqrt{(s-a)(s-b)(s-c)(s-d)} }[s=\tfrac12(a+b+c+d), a=\surd2,b=\surd2,c=\surd3,d=1] \subsubsection{Suppressing display of the vv-list} \label{subsec:evalVvSuppresList} \paragraph{Star (\texttt{{*}}) option} If display of the vv-list is not wanted at all, only the numerical result, it suffices to attach an asterisk (star) to the \verb`\eval` command, giving a `naked' result: \begin{centred} \verb`\eval*{ hA_C }[A_C=\pi r^2,h=4/3,r=1]` $\Longrightarrow$ \eval*{ hA_C }[A_C=\pi r^2,h=4/3,r=1]. \end{centred} The star option for a multi-formula calculation evaluates each formula and presents the numerical result of each calculation with a space between; it is minimal and inelegant: \begin{centred} \verb`\eval*[ff]{ \surd x, x, x^2 }[x=\pi]` $\Longrightarrow$ \eval*[ff]{ \surd x, x, x^2 }[x=\pi] \end{centred} However, the \verb`pp` setting is available to add a comma (for instance) and the \verb`sep` setting can change the space – perhaps \verb`sep=\quad`. Note that with the star option a negative result will display with a hyphen for the minus sign. \begin{centred} \verb`\eval*{ y }[y=ax+b,x=2,a=-2,b=2]` $\Longrightarrow$ \eval*{ y }[y=ax+b,x=2,a=-2,b=2], \end{centred} In a math environment, the hyphen will display as a minus sign. Wrapping \verb`\eval*` around math delimiters or using the \verb`env` option has no effect – the \verb`*` dominates. \paragraph{No math environment:} In the absence of a math environment, recall from §\ref{subsec:introResultDisplay}, \verb`\eval` (no star!) automatically presents the numerical result \emph{without vv-list} between \verb`$` delimiters, (so that negative values display with a proper minus sign): \begin{centred} \verb`\eval{ y }[y=ax+b,x=2,a=-2,b=2]` $\Longrightarrow$ \eval{ y }[y=ax+b,x=2,a=-2,b=2]. \end{centred} \paragraph{Settings option:} Display of the vv-list can also be suppressed through the settings option, by writing \verb`vv= ` there – i.e.\ by giving the key \verb`vv` an empty value. If the example above is too bare, then perhaps \begin{centred} \verb`\eval[vv=]{$ V_C $}[V_C=h\pi r^2,h=4/3,r=1]` $\Longrightarrow$ \eval[vv=]{$ V_C $}[V_C=h\pi r^2,h=4/3,r=1] \end{centred} is more acceptable? See §\ref{subsec:settingsVvDisplayChangeLocal} for a fuller discussion of the \verb`vv` setting. \paragraph{Scriptstyle contexts: } In versions of \texttt{numerica} before version 3, display of the vv-list was automatically suppressed in scriptstyle (and scriptscriptstyle) contexts. This occurred by means of \TeX 's \verb`\mathchoice` command. Version 3.0.0 of \texttt{numerica} has dispensed with\texttt{ }\verb`\mathchoice` and requires the user to suppress display in these contexts (if so wished), by starring the \verb`\eval` command: \begin{centred} \verb`$e^{\eval*{xy}[x=\pi,y=1/e]}$` $\Longrightarrow$ $e^{ \eval*{xy}[x=\pi,y=1/e]}$ \end{centred} \paragraph{Empty vv-list suppressed:} Should the vv-list be empty, or display of \emph{all} variables be suppressed by wrapping each in braces (see next, §\ref{subsec:evalVvSuppressVars}), then \emph{nothing} is displayed where the vv-list would normally be: \begin{centred} \verb`$ V_C=\eval{ hA_C }[{A_C}=\pi r^2,{h}=4/3,{r}=1] $.` $\Longrightarrow$ $ V_C=\eval{ hA_C }[{A_C}=\pi r^2,{h}=4/3,{r}=1]. $ \end{centred} \subsubsection{Suppressing display of items} \label{subsec:evalVvSuppressVars}You may wish to retain some variables in the vv-list display, but not all. For those variables you wish omitted from the display, wrap each variable (but not the equals sign or value) in braces. When calculating the volume of a cylinder in a previous example, the base area $A_{C}$ has a different status from the `fundamental' variables $r$ and $h$. It is an intermediate value, one that we pass through on the way to the final result. To suppress it from display enclose the variable in braces: \begin{centred} \verb`$ V_C=\eval{ hA_C }[{A_C}=\pi r^2,h=4/3,r=1] $` $\Longrightarrow$ $ V_C=\eval{ hA_C }[{A_C}=\pi r^2,h=4/3,r=1] $. \end{centred} As you can see, $A_{C}$ no longer appears in the displayed vv-list. Of course the name and its value are still recorded `behind the scenes' and can still be used in calculations. Note that the braces enclose only the variable name, not the equals sign or the value. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \subsection{Abusing multi-token variable names} \label{subsec:evalDon't-do-this!}A variable name is what lies to the left of the equals sign of an item in the vv-list. Since multi-token variables are converted to single tokens before any calculating is done, it is possible to sin. We can, for instance, make $\sin\pi$ a variable name and produce an absurdity: \begin{centred} \verb`\eval{$ \sin\pi $}[{\sin\pi}=1]` $\Longrightarrow$ \eval{$ \sin\pi $}[{\sin\pi}=1]; \end{centred} or similarly treat a number as a variable name and produce another: \begin{centred} \verb`\eval{$ -1 $}[{-1}=1]` $\Longrightarrow$ \eval{$ -1 $}[{-1}=1]. \end{centred} What is happening here is that the multi-token `variables' \verb`\sin\pi` and \verb`-1` are converted, right at the start of proceedings, to single tokens like \verb`\nmc_a`, \verb`\nmc_b`. These \TeX{} macros expand to their respective multi-token variable names when \emph{displayed}, but for calculating within \texttt{numerica} the single token is used. By this means it is easy to construct whatever grotesqueries you like. \medskip{} Should \texttt{numerica} try to check variable names to avoid consequences like this? I see no reasonable way of doing so. Digits, and symbols like \verb`(` and \verb`+`, can easily be part of valid variable names – $k^{+}$, $x_{1}$, $C_{n}^{(0)}$ and so on. It is left to the user, in any \emph{public} document, to avoid such sins (which can easily be constructed in \LaTeX{} without recourse to \verb`\eval` at all, should the user so wish). See also §\ref{subsec:supplMacrosDisplay} where a similar issue arises with user-defined macros.\end{shaded}% \end{minipage} \section{Formatting the numerical result} \label{sec:evalRoundingEtc}Internally, values are stored to $16$ significant figures (if available), calculations are carried out to $16$ significant figures, but only rarely are results displayed to $16$ figures. Generally, they are rounded to some smaller number of figures. The default `out of the box' rounding value is $6$, meaning at most $6$ decimal places are shown. (It can of course be reset with the \verb`rounding` package option, e.g. \verb`rounding=4`; see §§\ref{subsec:introPackagesOptions}, \ref{subsec:evalRounding-value}.) So far, nearly all results have been rounded to the default figure, although not all digits are always displayed – for instance if the sixth one is $0$, or the result is an integer. But \texttt{numerica} is not limited to the decimal presentation of results. Scientific notation is also available, as is fraction-form output with numerator and denominator both integers, and boolean output when the formula being evaluated is a comparison, treated by the \verb`\eval` command not as a statement like \emph{`A is less than B'} but rather as a question: \emph{`Is A less than B?'}. The appearance of the result in any of these various formats can be chosen and customized by means of a square-bracketed optional argument following the vv-list – or the formula if there is no vv-list. This optional argument may contain a number of juxtaposed items from these possibilities: \begin{itemize} \item a question mark \verb`?` which gives boolean output, $1$ for true, $0$ for false; see §\ref{subsec:evalBoolean-output}; \begin{itemize} \item a second question mark, \verb`??`, which gives boolean output $T$ for true, $F$ for false; \item a third question mark, \verb`???`, which gives boolean output \verb`T` for true, \verb`F` for false; \end{itemize} \item a slash \verb`/` which gives output in slash-fraction form with integers for both numerator and denominator; see §\ref{subsec:evalFraction-form-output}; if followed by \verb`s` the fraction will be formed with the \verb`\sfrac` command from the \verb`xfrac` package if loaded, or in scriptstyle slash fraction form if not; \begin{itemize} \item a second slash, \verb`//`, which gives output in fraction form using \verb`\frac` with integers for both numerator and denominator; if followed by \verb`t` or \verb`d` the fraction will be formed with, respectively, the \verb`\tfrac` or \verb`\dfrac` commands from \verb`amsmath`; \end{itemize} \item an integer, the \emph{rounding value}, positive, negative or zero, specifying how many decimal places to display the result to, or to how many zeros after the decimal point fraction-form output approximates the result; see §\ref{subsec:evalRounding-value} and §\ref{subsec:evalFraction-form-output}; \item an asterisk, {*}, which pads the result with zeros should it not display as many decimal places as the rounding value specifies; see §\ref{subsec:evalPadding-with-zeros}; \item the character \verb`x` (lower case!) which presents the result in `proper' scientific notation (a form like $1.2345\times10^{5}$ for 123450) except for numbers in the interval \verb`[1,10)`; see §\ref{subsec:evalSciNotation1to10}; \begin{itemize} \item the character \verb`x` repeated, \verb`xx`, which extends the notation to numbers in the interval \verb`[1,10)`; \end{itemize} \item the character \verb`t` (lower case!) which presents the result in a style of scientific notation useful in tables (a form like $(5)1.2345$ for 123450) except for numbers in the interval \verb`[1,10)`; see §\ref{subsec:evalSciNotation1to10}; \begin{itemize} \item the character \verb`t` repeated, \verb`tt`, which extends the notation to numbers in the interval \verb`[1,10)`; \end{itemize} \item a letter other than \verb`x` or \verb`t`, usually one of the letters\texttt{ }\verb`e`, \verb`d`, \verb`E`, \verb`D`, which presents the result in scientific notation with that letter as the exponent mark (a form like $1.2345\text{e}5$ for $123450$); see §\ref{subsec:evalSciNotation1to10}; \begin{itemize} \item the letter repeated – say \verb`dd` – which extends the notation to numbers in the interval \verb`[1,10)`. \end{itemize} \end{itemize} If you use \verb`?` in the same specification as some other character, the \verb`?` prevails; if you use \verb`/` in the same specification as some other character except for \verb`?`, the \verb`/` prevails; if you use \verb`x` in the same specification as some other character except for \verb`?` or \verb`/`, the \verb`x` prevails; if you use \verb`t` in the same specification as some other character except for \verb`?`, \verb`/` or \verb`x`, the \verb`t` prevails: \verb`?`$\succ$\verb`/`$\succ$\verb`x`$\succ$\verb`t`$\succ$\ldots{} (where $\succ$ means `prevails over'). \subsection{Rounding value } \label{subsec:evalRounding-value}If the number is displayed as a decimal, the rounding value specifies the number of decimal places displayed. If a number is displayed in scientific notation (see below §\ref{subsec:evalScientificNotation}) that is still true, but it can mean differences in the overall number of digits displayed. For the moment, I show the effect of rounding in a purely decimal display: \begin{centred} \verb`\eval{ 1/3 }[4],\qquad \eval{ 1/3 }` $\Longrightarrow$ \eval{ 1/3 }[4],\qquad\eval{ 1/3 }. \end{centred} In the first case \verb`4` was entered in the number-format option and the result is displayed to four decimal places; in the second, the default rounding value of $6$ takes effect. Following the default behaviour in \texttt{l3fp}, which is the calculational engine used by \texttt{numerica}, `ties' are rounded to the nearest \emph{even} digit. Thus a number ending $55$ with a `choice' of rounding to $5$ or $6$ rounds up to the even digit $6$, and a number ending $65$ with a `choice' of rounding to $6$ or $7$ rounds down to the even digit $6$: \begin{centred} \verb`\eval[pp,ff]{ 0.1234555, 0.1234565 }` $\Longrightarrow$ \eval[pp,ff]{0.1234555,0.1234565}. \end{centred} \texttt{l3fp} works to 16 significant figures and never displays more than that number (and often fewer). \begin{itemize} \item In the following, although I have specified a rounding value of $19$, only $16$ decimal places are displayed (with the final digits rounded up): \end{itemize} \begin{centred} \verb`\eval{ 0.12345678912345678912 }[19]` $\Longrightarrow$ \eval{ 0.12345678912345678912 }[19]\medskip{} \verb`\eval{ 1.12345678912345678912 }[19]` $\Longrightarrow$ \eval{ 1.12345678912345678912 }[19] \end{centred} \begin{itemize} \item Now I add ten zeros after the decimal point, meaning that all $19$ decimal places specified by the rounding value can be displayed in the first since the ten zeros do not contribute to the significant figures, but in the second, by changing the figure before the decimal point to $1$, the ten zeros added \emph{do} contribute to the significant figures: \end{itemize} \begin{centred} \verb`\eval{ 0.0000000000123456789 }[19]` $\Longrightarrow$ \eval{ 0.0000000000123456789 }[19]\medskip{} \verb`\eval{ 1.0000000000123456789 }[19]` $\Longrightarrow$ \eval{ 1.0000000000123456789 }[20] \end{centred} \begin{itemize} \item Lastly, I have added $9$ digits before the decimal point: \end{itemize} \begin{centred} \verb`\eval{ 987654321.123456789 }[19]` $\Longrightarrow$ \eval{ 987654321.123456789 }[19] \end{centred} In all cases, no more than $16$ \emph{significant} figures are displayed, although the number of decimal places displayed may exceed $16$. It is possible to use \emph{negative} rounding values. Such a value replaces the specified number of digits \emph{before} the decimal point with zeros. \begin{centred} \verb`\eval{ 987654321.123456789 }[-4]` $\Longrightarrow$ \eval{ 987654321.123456789 }[-4] \end{centred} A rounding value of $0$ rounds to the nearest integer: \begin{centred} \verb`\eval{ 987654321.123456789 }[0]` $\Longrightarrow$ \eval{ 987654321.123456789 }[0] \end{centred} If you wish to change the \emph{default} rounding value from $6$ to some other value, this can be done by means of the package option \verb`rounding`. For example, calling \texttt{numerica} like this, \begin{verbatim} \usepackage[rounding=4]{numerica} \end{verbatim} will make $4$ the new default rounding value. The rounding value also plays a part in how closely fraction-form output approximates the calculated result (§\ref{subsec:evalFraction-form-output}), and how many terms are used to evaluate `infinite' sums (§\ref{tab:calcStoppingCriterionSettings}). \subsection{Padding with zeros } \label{subsec:evalPadding-with-zeros}A result may contain fewer decimal places than the rounding value specifies, the trailing zeros being suppressed by default (this is how \texttt{l3fp} does it). Sometimes, perhaps for reasons of presentation like aligning columns of figures, it may be desirable to pad results with zeros – we have already met an example at §\ref{subsec:intoMultiFormulaPunctuation}. Padding is achieved by inserting an asterisk into the final optional argument of the \verb`\eval` command: \begin{centred} \verb`\eval{ 1/4 }[4]` $\Longrightarrow$ \eval{ 1/4 }[4],\medskip{} \verb`\eval{ 1/4 }[4*],\quad \eval{ 1/4 }[*4]` $\Longrightarrow$ \eval{ 1/4 }[4*],\quad\eval{ 1/4 }[*4]. \end{centred} As you can see, it doesn't matter if there is a rounding value also present (the example at §\ref{subsec:intoMultiFormulaPunctuation}, using the default rounding value, had none), nor the order in which the asterisk and rounding value are entered. \subsection{Scientific notation } \label{subsec:evalScientificNotation} \texttt{numerica} can output numbers in various scientific notations. Entering \verb`x` (lower case) in the number-format option produces the `pure' form: \begin{centred} \verb`\eval[pp,ff]{ 2^{256}, 2^{-256} }[x]` $\Longrightarrow$ $\vsp$\eval[pp,ff]{ 2^{256}, 2^{-256} }[x]. \end{centred} With the default rounding value, as here, one digit is shown before the decimal point and $6$ digits after. Alternatively, you can enter some other letter in the number-format option, generally \verb`e`, to generate a less elegant, more utilitarian output: \begin{centred} \verb`\eval[pp,ff]{ 3^{81}, e^{-81} }[e]` $\Longrightarrow$ \eval[pp,ff]{ 3^{81}, 3^{-81} }[e]. \end{centred} Other letters sometimes used for this purpose are \verb`E`, \verb`d` and \verb`D`, but \texttt{numerica} will accept \emph{any} letter (although \verb`x` and \verb`t` produce distinctive output). The `e' in the output is the \emph{exponent mark}, separating the \emph{significand} ($1.234$) from the \emph{exponent} ($3$). In scientific notation, the significand always has one \emph{non-zero} digit before the decimal point (except for $0$ itself). For scientific notation the rounding value still means the number of decimal places displayed – by default, $6$. This can mean different numbers of digits being shown from those displayed in `ordinary' decimal form. Compare \verb`\eval{ 123.456789 }` $\Longrightarrow$ \eval{ 123.456789 }, where nine significant figures are displayed, with \verb`\eval{ 123.456789 }[e]` $\Longrightarrow$ \eval{ 123.456789 }[e] where only seven are, one before the decimal point and six after. In the other direction, only five significant figures are shown in the `ordinary' decimal form \verb`\eval{ 0.0123456789 }` $\Longrightarrow$ \eval{ 0.0123456789 }, whereas in scientific notation \verb`\eval{ 0.0123456789 }[e]` $\Longrightarrow$ \eval{ 0.0123456789 }[e] once again seven are on display. Negative rounding values are pointless for scientific notation. Sometimes letters other than `e' are used for the exponent mark, particularly `E' or `d' or `D'. \begin{centred} \verb`\eval{$ 1/123456789 $}[4d]`\texttt{ $\Longrightarrow$} \eval{$ 1/123456789 $}[4d]. \end{centred} But when \verb`x` is inserted in the trailing optional argument, the output is in the form $d_{0}.d_{1}\ldots d_{m}\times10^{n}$ (except when $n=0$), where each $d_{i}$ denotes a digit. \begin{centred} \verb`\eval{$ 1/123456789 $}[4x*]`\texttt{ $\Longrightarrow$ }\eval{$ 1/123456789 $}[4x*] . \end{centred} As you can see, padding with zeros still applies in scientific notation and is activated, as before, with an asterisk in the number-format option. The requirements of tables leads to another form of scientific notation. Placing \verb`t` in the trailing argument turns on this table-ready form: \begin{centred} \verb`\eval{$ 1/123456789 $}[4t*]`\texttt{ $\Longrightarrow$ }\eval{$ 1/123456789 $}[4t*]. \end{centred} This is discussed more fully in the documentation for the \texttt{numerica-tables} package. The order in which items are entered in the number-format option doesn't matter: \begin{centred} \verb`\eval{$ 1/125 $}[*e4]` $\Longrightarrow$ \eval{$ 1/125 $}[*e4],\medskip{} \verb`\eval{$ 1/125 $}[4e*]` $\Longrightarrow$ \eval{$ 1/125 $}[4e*]. \end{centred} \subsubsection{Numbers in the interval \texttt{{[}1,10)}} \label{subsec:evalSciNotation1to10}Usually when scientific notation is being used, numbers with magnitude in the interval $[1,10)$ are rendered in their normal decimal form, $3.14159$ and the like. Occasionally it may be desired to present numbers in this range in scientific notation (this can be the case in tables where the alignment of a column of figures might be affected). \texttt{numerica} offers a means of extending scientific notation to numbers in this range by repeating the letter chosen as the exponent mark in the trailing optional argument. \begin{centred} \verb`\eval{$ \pi $}[4xx]` $\Longrightarrow$ \eval{$ \pi $}[4xx] \end{centred} \subsubsection{\textbackslash eval{*} and scientific notation} Starring the \verb`\eval` command gives a number-only result which can be presented in scientific notation: \begin{centred} \verb`\eval*{ \pi^\pi }[e]` $\Longrightarrow$ \eval*{ \pi^\pi }[e] \end{centred} There is one catch: if you substitute \verb`x` for \verb`e` here, compilation will halt and \LaTeX{} will state \verb`Missing $ inserted.` This is because an \verb`x` in the number-format option means a \verb`\times` in the output and that requires a math environment to display. It is up to you, as the user, to provide the necessary delimiters \emph{outside} the \verb`\eval*` command. (Alternatively, use \verb`\eval` without the star and without any delimiters whatever. Dollar signs are automatically placed around the result.) \subsection{Fraction-form output} \label{subsec:evalFraction-form-output}The \verb`\eval` command can output numbers in fraction form by including in the number-format specification either one or two slashes: \begin{centred} \verb`\eval[pp,ff]{0.333333, 1.875}[4/]` $\Longrightarrow$ \eval[pp,ff]{0.333333,1.875}[4/];\medskip{} \verb`\eval[pp,ff]{\pi, e}[2//]` $\Longrightarrow$ \eval[pp,ff]{\pi, e}[2//]. \end{centred} A single slash results in a textstyle slash fraction; two slashes produce a \verb`\frac`-tion. Always, numerator and denominator are integers. The rounding value determines how close the fraction is to the calculated result. Consider \begin{verbatim} \eval{\pi}[1//],\quad \eval{\pi}[2//], \eval{\pi}[3//],\quad \eval{\pi}[6//]. \end{verbatim} $\Longrightarrow$ \eval{\pi}[1//],\quad\eval{\pi}[2//],\quad \eval{\pi}[3//],\quad\eval{\pi}[6//], \medskip{} \noindent and compare these results against $\pi$: \begin{verbatim} \eval[env=alignat*,pp,p=.,ff]{ \pi-\tfrac{19}6, \pi-\tfrac{22}7, \pi-\tfrac{267}{85}, \pi-\tfrac{355}{113} }[8*] \end{verbatim} $\Longrightarrow$ \eval[env=alignat*,pp,p=.,ff]{ \pi-\tfrac{19}6, \pi-\tfrac{22}7, \pi-\tfrac{267}{85}, \pi-\tfrac{355}{113} }[8*]In each case the fraction approximates the correct result to at least as many decimal places as specified in the rounding value – the difference between pi and the fraction is zero to that rounding value. Sometimes, as evident with the familiar approximations $22/7$ and $355/113$, the difference is zero to twice the number of digits in the denominator – these are exceptionally good approximations. The example illustrates the use of an \verb`alignat*` environment to ensure the results line up, including taking account of the minus signs. What happens if I seek a still more accurate approximation – say to (at least) seven places of decimals? The result is a message: \begin{centred} \verb`\eval{\pi}[7//]` $\Longrightarrow$ \eval{ \pi}[7//] \end{centred} By default \texttt{numerica} searches denominators from 1 to $200$ before halting the search and producing the message. The program offers two settings that may assist here. The first is the \verb`/max` setting which allows the user to specify the maximum denominator tried, e.g.\ putting \verb`/max = 1000` in the settings option of the \verb`\eval` command would allow the search to continue up to a denominator of $1000$. But perhaps that means waiting too long? The user can also specify an initial value to start searching from with the \verb`/min` setting, by entering in the settings option, say, \verb`/min = 500`, which would mean searching from an initial denominator of $500$. By default \verb`/min = 1` and \verb`/max = 200`. To test the settings equate both to $113$: \begin{centred} \verb`\eval[/min=113,/max=113]{\pi}[6//]` $\Longrightarrow$ \eval[/min=113,/max=113]{\pi}[6//]. \end{centred} Performing a similar exercise with other irrational numbers like $e$, $\phi$ and $\surd2$, one realizes just how good this particular approximation is. \subsubsection{Refining the form of fraction} The form of the fraction output can be refined by adding a qualifying letter to the single or double slash in the number format option. By adding an \verb`s` after a single slash, \verb`/s`, it is possible to get scriptstyle numbers in a slash fraction. If the \texttt{xfrac} package\footnote{\texttt{xfrac} is included in the \texttt{l3packages} bundle.} has been loaded (as it has been for the present document), then the fraction takes this form: \begin{centred} \verb`\eval{$ \pi $}[2/s]` $\Longrightarrow$ \eval{$ \pi $}[2/s]. \end{centred} This is the result of the \verb`\sfrac` command from the \texttt{xfrac} package. If that package had not been loaded then the fraction would have been presented in the form $\scriptstyle 22/7$. By adding a \verb`t` or \verb`d` after two slashes, \verb`//t` or \verb`//d`, it is possible to force textstyle or displaystyle output by means of \texttt{amsmath}'s \verb`\tfrac` or \verb`\dfrac` commands (in place of \verb`\frac`). For example, even in a displaystyle environment, \begin{centred} \verb`\eval[p]{\[ \pi \]}[6//t]` $\Longrightarrow$ \eval[p]{\[ \pi \]}[6//t] \end{centred} with the \verb`//t` specification, and similarly, in a textstyle environment you can force a displaystyle fraction with the \verb`//d` specification. \subsection{Boolean output} \label{subsec:evalBoolean-output}\texttt{l3fp} can evaluate comparisons, outputting $0$ if the comparison is false, $1$ if it is true. By entering a question mark, \verb`?`, in the trailing optional argument, you can force \texttt{numerica} to do the same depending as the result of a calculation is zero or not. (The expression being evaluated does not need to be a comparison, \verb`\eval{\pi}[?]` $\Longrightarrow$ \eval{\pi}[?], but comparisons are what this is designed for.) Possible comparison relations are \verb`=`, \verb`<`, \verb`>`, \verb`\ne`, \verb`\neq`, \verb`\ge`, \verb`\geq`, \verb`\le`, \verb`\leq`. Although programming languages use combinations like \verb`<=` or \verb`>=` and, from version 3.0.0 \verb`\eval` will accept these without raising an error, this is not part of mathematical practice. An example of boolean output where the relation is equality exhibits a numerological curiosity: \begin{centred} \verb`\eval[p=.]{\[ \frac1{0.0123456789}=81 \]}[5?]` $\Longrightarrow$ \eval[p=.]{\[ \frac1{0.0123456789}=81 \]}[5?] \end{centred} The expression on the left is to be read as a \emph{question}: `Is $1/0.0123456789$ equal to $81$?', not as a statement; the arrow points to the answer, in this instance $1$, meaning \emph{true}. But notice the $5$ alongside the question mark in the trailing argument. That is critical. Change it to $6$ (or omit it since the default rounding value is $6$) and the outcome is different: \begin{centred} \verb`\eval[p=.]{\[ \frac1{0.0123456789}=81 \]}[6?]` $\Longrightarrow$ \eval[p=.]{\[ \frac1{0.0123456789}=81 \]}[6?] \end{centred} Now the relation is \emph{false}. Evaluating the fraction to more than $6$ places, say to $9$, we can see what is going on: \begin{centred} \verb`\eval{$ 1/0.0123456789 $}[9]` $\Longrightarrow$ \eval{$ 1/0.0123456789 $}[9]. \end{centred} In other words, the question posed by the \verb`?` specification is not `Is $1/0.0123456789$ equal to $81$?' but `Is $1/0.0123456789$ equal to $81$ \emph{to the specified number of decimal places}?' To $5$ decimal places it is; to $6$ decimal places it is not. \subsubsection{Outputting \texttt{T} or \texttt{F}} To my eye, outputting $0$ or $1$ in response to a question like $1/0.0123456789=81$ is confusing. It is easy to change the boolean output from $0,1$ to a more appropriate $F,T$, or \texttt{$\texttt{F,\texttt{T}}$} by duplicating ($F,T$) or triplicating (\texttt{$\texttt{F,\texttt{T}}$}) the question mark in the number-format option. \begin{centred} \verb`\eval[p=.]{\[ \frac1{0.0123456789}=81 \]}[6???]` $\Longrightarrow$ \eval[p=.]{\[ \frac1{0.0123456789}=81 \]}[6???] \end{centred} The default boolean output format is chosen to be $0,1$ in case an \verb`\eval` command is used within another \verb`\eval` command (`nesting'– see Chapter~\ref{sec:miscNesting}~). The inner command needs to output a \emph{numerical} answer. \subsubsection{Rounding error tolerance} \label{subsec:evalToleranceRounding}If at least one of the terms in a comparison is the result of a calculation, then it's value is likely to contain rounding errors. What level of rounding error can we tolerate before such errors interfere with the comparison being made? \texttt{l3fp} tolerates none. It decides the truth or falsity of a comparison to all $16$ significant figures: 1.000 0000 0000 0000 and 1.000 0000 0000 0001 are \emph{not }equal in \texttt{l3fp}. But for most purposes this will be far too severe a criterion. Suppose our comparison relation is $\varrho$, denoting one of =, <, >, \verb`\le`, etc. If $X\rel Y$ then $X-Y\rel Y-Y$, i.e.\ $X-Y\rel0$. This is what \texttt{numerica} does. It takes the right-hand side of the relation from the left-hand side and then compares the \emph{rounded} difference under $\varrho$ to $0$. The rounding value used is the number specified with the question mark in the trailing argument of the \verb`\eval` command or, if no number is present, the default rounding value (`out of the box' this is $6$). Thus, in a recent example, $1/0.0123456789-81$ when rounded to $5$ decimal places is $0.00000$, indistinguishable from zero at this rounding value; hence the equality $1/0.0123456789=81$ is true. But when rounded to $6$ places it is $0.000001$ which \emph{is} distinguishable from zero and so the equality is false. Truth or falsity depends on the rounding value. When dealing with numbers generated purely mathematically, rounding values of $5$ or $6$ are likely to be too small. More useful would be rounding values closer to \texttt{l3fp}'s $16$ – perhaps $14$? – depending on how severe the calculations are that generate the numbers. However if the numbers we are dealing with come from outside mathematics, from practical experiments perhaps, then even a rounding value of $5$ or $6$ may be too large. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% Mathematically, the claim that $X=Y$ at a rounding value $n$ is the claim that \[ \abs{X-Y}\le5\times10^{-(n+1)}. \] since this rounds \emph{down} to zero at $n$ places of decimals. This gives a more accurate test of equality than doing things in the opposite order – rounding each number first and then taking the difference. One might, for instance, have numbers like $X=0.12345$, $Y=0.12335$. Rounding to $n=4$ places, both round to $0.1234$ and yet the difference between them is $0.0001$ – they are distinguishable numbers to $4$ places of decimals. This is why \texttt{numerica} forms the difference \emph{before }doing the rounding.\end{shaded}% \end{minipage} \subsubsection{And, Or, Not} For logical And \LaTeX{} provides the symbols \verb`\wedge` and \verb`\land`, both displaying as $\land$, but \texttt{numerica} adds thin spaces ( \verb`\,` ) around the symbol for \verb`\land` (copying the package \texttt{gn-logic14.sty}). For logical Or \LaTeX{} provides the symbols \verb`\vee` and \verb`\lor`, both displaying as $\lor$, but again \texttt{numerica} adds thin spaces around the symbol for \verb`\lor`. \begin{centred} \verb`\eval{$ 1<2 \wedge 2<3 $}[??]` $\Longrightarrow$ \eval{$ 1<2 \wedge 2<3 $}[??], \verb`\eval{$ 1<2 \land 2<3 $}[???]` $\Longrightarrow$ \eval{$ 1<2 \land 2<3 $}[???]. \end{centred} To my eye the second of these with its increased space around the wedge symbol displays the meaning of the overall expression better than the first. Both And and Or have equal precedence; in cases of ambiguity the user needs to parenthesize as necessary to clarify what is intended. \LaTeX{} provides two commands for logical Not, \verb`\neg` and \verb`\lnot`, both displaying as $\lnot$ . Not binds tightly to its argument: \begin{centred} \verb`\eval{$ \lnot A \land B $}[A=0,B=0]` $\Longrightarrow$ \eval{$ \lnot A \land B $}[A=0,B=0]. \end{centred} Here \verb`\lnot` acts only on the $A$; if it had acted on $A\land B$ as a whole the result would have been different: \begin{centred} \verb`\eval{$ \lnot(A \land B) $}[A=0,B=0]` $\Longrightarrow$ \eval{$ \lnot(A \land B) $}[A=0,B=0]. \end{centred} For a little flourish, I evaluate a more complicated logical statement:\footnote{Quoting from an article in \emph{Quanta Magazine} (August 2020) by Kevin Hartnett: `Let’s say you and two friends are planning a party. The three of you are trying to put together the guest list, but you have somewhat competing interests. Maybe you want to either invite Avery or exclude Kemba. One of your co-planners wants to invite Kemba or Brad or both of them. Your other co-planner, with an ax to grind, wants to leave off Avery or Brad or both of them. Given these constraints, you could ask: Is there a guest list that satisfies all three party planners?' I have written $C$ for Kemba, $A$ and $B$ for Avery and Brad.} \begin{verbatim} \eval{$(A\lor\lnot C)\land(C\lor B)\land (\lnot A\lor\lnot B)$}[A=1,B=0,C=1][???] \end{verbatim} $\Longrightarrow$ \eval{$(A\lor\lnot C)\land(C\lor B)\land (\lnot A\lor\lnot B)$}[A=1,B=0,C=1][???]. \subsubsection{Chains of comparisons} \texttt{numerica} can handle chains of comparisons like $1<2<1+2<5-1$. `Behind the scenes' it inserts logical And-s into the chain, $1<2\land2<1+2\land1+2<5-1$, and evaluates the modified expression: \begin{centred} \verb`\eval{$ 1<2<1+2<5-1 $}[???]` $\Longrightarrow$ \eval{$ 1<2<1+2<5-1 $}[???]. \end{centred} \subsubsection{\texttt{amssymb} comparison symbols} \label{subsec:evalAmssymb-comparisons}\texttt{numerica} accepts some alternative symbols for the basic comparison relations from the \texttt{amssymb} package provided that package is loaded, i.e.\ the preamble of your document includes the statement \begin{verbatim} \usepackage{amssymb} \end{verbatim} The variants from this package are: \verb`\leqq` ( $\leqq$ ), \verb`\leqslant` ( $\leqslant$ ), \verb`\geqq` (~$\geqq$~), and \verb`\geqslant` ( $\geqslant$ ).\footnote{No, that is not \texttt{eggplant}.} There are also negations: \verb`\nless` ( $\nless$ ), \verb`\nleq` (~$\nleq$~), \verb`\nleqq` ( $\nleqq$ ), \verb`\nleqslant` ( $\nleqslant$ ), \verb`\ngtr` ( $\ngtr$ ), \verb`\ngeq` ( $\ngeq$ ), \verb`\ngeqq` ( $\ngeqq$ ), \verb`\ngeqslant` ( $\ngeqslant$ ). \chapter{Calculational details} \section{Arithmetic} \label{sec:calcArithmetic}Addition, subtraction, multiplication, division, square roots, \emph{$n$}-th roots, and exponentiating (raising to a power) are all available. Multiplication can be rendered explicitly with an asterisk, \begin{centred} \verb`\eval{$ 9*9 $}` $\Longrightarrow$ \eval{$ 9*9 $}, \end{centred} but that's ugly. More elegant is to use \verb`\times`: \begin{centred} \verb`\eval{$ 9\times9 $}` $\Longrightarrow$ \eval{$ 9\times9 $}. \end{centred} \verb`\cdot` is also available and in many cases juxtaposition alone suffices: \begin{centred} \verb`\eval{$ \surd2\surd2 $}` $\Longrightarrow$ \eval{$ \surd2\surd2 $}, \verb`\eval{$ ab $}[a=123,b=1/123]` $\Longrightarrow$ \eval{$ ab $}[a=123,b=1/123]. \end{centred} Division can be rendered in multiple ways too. Using a comma list for a multi-formula evaluation (and the \verb`ff` setting), \begin{centred} \verb`\eval[p=.,ff]{\[ 42/6, 42\div6, \frac{42}6 \]}` $\Longrightarrow$ \eval[p=.,ff]{\[ 42/6, 42\div6, \frac{42}6 \]} \end{centred} In a displaystyle environment, \verb`\frac` displays as shown. In a textstyle environment it displays as $\frac{42}{6}$. If you want to force a textstyle display, even in a displaystyle environment, use \verb`\tfrac` (from \texttt{amsmath}) and, conversely, if you want to force a displaystyle display, even in a textstyle environment, use \verb`\dfrac`. If the package \texttt{xfrac} is loaded, then slash fractions are rendered with scriptstyle numbers, \verb`\eval[p]{\[ \sfrac{42}{6} \]}` $\Longrightarrow$ \eval[p]{\[ \sfrac{42}{6} \]} even in a displaystyle environment. If \verb`xfrac` is not loaded, then \texttt{numerica} defines \verb`\sfrac` to expand to a scriptstyle slash fraction, e.g. ${\scriptstyle 42/6}$. Note that since juxtaposition means multiplication, a combination like $42\tfrac{1}{6}$\texttt{ }also evaluates to $7$ within an \verb`\eval` command; it does not mean `forty two and a sixth'. Such fractions need to be entered as improper fractions to evaluate correctly – for instance, `two and a half' entered as $\tfrac{5}{2}$ (as one does anyway in mathematical expressions because of the ambiguity in a form like $2\tfrac{1}{2}$). Powers are indicated with the superscript symbol \verb`^`. It is clear from the braced \LaTeX{} grouping that a `tower' of superscripts is evaluated from the top down. Thus $3^{2^{3}}$is $3^{8}$ $(=9^{4})$, not $9^{3}=\eval{9^{3}}$: \begin{centred} \verb` \eval{$ 3^{2^3} $}` $\Longrightarrow$ \eval{$ 3^{2^3} $} . \end{centred} \section{Square roots and $n$-th roots} \label{sec:calcSquareRootsEtc}Let us check that 3, 4, 5 and 5, 12, 13 really are Pythagorean triples (I use \verb`\sqrt` in the first, \verb`\surd` in the second): \begin{centred} \verb`\eval[ff]{\[ \sqrt{3^2+4^2}, \surd(5^2+12^2) \]}` $\Longrightarrow$ \eval[ff]{\[\sqrt{3^{2}+4^{2}}, \surd(5^2+12^2)\]} \end{centred} The \verb`\sqrt` command has an optional argument which can be used for extracting $n$-th roots of a number. In \texttt{numerica}, when used with the \verb`\sqrt` command, $n$ is assumed to be a \emph{positive integer}, in practice generally a \emph{small} positive integer like $3$ or $4$. \begin{centred} \verb`\eval{$ \sqrt[4]{81} $}` $\Longrightarrow$ \eval{$ \sqrt[4]{81} $},\medskip{} \verb`\eval{$ \sqrt[n]{125} $}[n=\floor{\pi}]` $\Longrightarrow$ \eval{$ \sqrt[n]{125} $}[n=\floor{\pi}]. \end{centred} For displaystyle expressions, the \verb`\sqrt` sign grows to accommodate the extra vertical height; the \verb`\surd` sign doesn't. Here is an example which uses the \verb`\mleft`, \verb`\middle`, \verb`\mright` commands from the package \texttt{mleftright} (requiring \verb`\usepackage{mleftright}` in the preamble of the present document). In the formula I have enlarged the $3$ of the cube root from the default \verb`\scriptscriptstyle` visible in the examples above to a more appropriately sized \verb`\scriptstyle`. \begin{verbatim} \eval[p=.]{\[ \sqrt[\scriptstyle3]{\! \mleft(\frac AD\middle/\frac BC\mright)} \]}[A=729,B=81,C=9,D=3] \end{verbatim} $\Longrightarrow$ \eval[p=.]{\[ \sqrt[\scriptstyle3]{\! \mleft(\frac AD\middle/\frac BC\mright)} \]}[A=729,B=81,C=9,D=3] As implemented in \texttt{numerica}, $n$-th roots found using \verb`\sqrt[n]` are restricted to positive integral \verb`n`. This raises an interesting question: if the `$n$' of an $n$-th root is the result of a calculation, what happens with rounding errors? The calculation may not produce an \emph{exact} integer. (This problem also arises with factorials; see §\ref{sec:calcFactorialsBinom}.) The solution employed in version 3.0.0 of \texttt{numerica} is simply to round to the nearest integer. This is simpler than in previous versions where an error could be raised in some rare situations. But it does mean that, e.g.\ \eval{$\sqrt[\pi]{27}$}, since $\pi$ rounds to $3$. In such cases, for the sake of the reader, a user should make the rounding explicit – as I did in an example above, wrapping $\pi$ in the \verb`\floor` command. \subsection{$n$-th roots of negative numbers} Odd (in the sense of `not even') positive integral roots of \emph{negative} numbers are available with \verb`\sqrt`, \begin{centred} \verb`\eval[p=.,ff]{\[ \sqrt[3]{-125}, \sqrt[3]{-3.375} \]}` $\Longrightarrow$\eval[p=.,ff]{\[ \sqrt[3]{-125}, \sqrt[3]{-3.375} \]} \end{centred} \subsection{Powers of $n$-th roots} In previous versions of \texttt{numerica}, raising an $n$-th root to a power when $n\ne2$ gave a false answer unless the $n$-th root was parenthesized before raising to the power. From version 3.0.0, the parentheses are unnecessary (but notice the thin space inserted before the $3$ in the second example to improve the visual appearance): \begin{centred} \verb`\eval[p=.,ff]{\[ \bigl(\sqrt[3]{-8}\,\bigr)^3, \sqrt[3]{-8}^{\,3} \]}` $\Longrightarrow$ \eval[p=.,ff]{\[ \bigl(\sqrt[3]{-8}\,\bigr)^3, \sqrt[3]{-8}^{\,3} \]} \end{centred} \subsection{Inverse integer powers } Of course to find an $n$-th root we can also raise to the inverse power, \begin{centred} \verb`\eval{$ 81^{1/4} $}` $\Longrightarrow$ \eval{$ 81^{1/4} $}. \end{centred} However, raising a \emph{negative} number to an inverse power generates an error even when, mathematically, it should not. This matter, which is a product of floating point representation of numbers, is discussed below in §\ref{subsec:errorsInverse-powers}. \section{Precedence and parentheses} The usual precedence rules apply: multiplication and division bind equally strongly and more strongly than addition and subtraction which bind equally stongly. Exponentiating binds most strongly. Evaluation occurs from the left. \begin{centred} \verb`\eval{$ 4+5\times6+3 $}` $\Longrightarrow$ \eval{$ 4+5\times6+3 $},\medskip{} \verb`\eval{$ 6\times10^3/2\times10^2 $}` $\Longrightarrow$ \eval{$ 6\times10^3/2\times10^2 $}, \end{centred} which may not be what was intended. Parentheses (or brackets or braces) retrieve the situation: \begin{centred} \verb`\eval{$ (4+5)(6+3) $}` $\Longrightarrow$ \eval{$ (4+5)(6+3) $},\medskip{} \verb`\eval{$ (6\times10^3)/(2\times10^2) $}` $\Longrightarrow$ \eval{$ (6\times10^3)/(2\times10^2) $}. \end{centred} When one writes $-4^{2}$ it is not clear what is intended: is it $-(4^{2})$ or $(-4)^{2}$? In \texttt{numerica} exponentiating binds most strongly; negative values must therefore be parenthesized when raised to a power. Thus \begin{centred} \verb`\eval[pp,ff]{$ -4^2, (-4)^2 $}` $\Longrightarrow$ \eval[pp,ff]{$ -4^2, (-4)^2 $}. \end{centred} \subsection{Command-form brackets} \label{subsec:calcCommandBrackets}Note that brackets of all three kinds are available also in command form: \verb`\lparen \rparen` (from \texttt{mathtools}) for \verb`( )`, \verb`\lbrack \rbrack` for \verb`[ ]`, and \verb`\lbrace \rbrace` for \verb`\{ \}`. \subsection{Modifiers\texttt{ (\textbackslash left}, \texttt{\textbackslash right}, \texttt{\textbackslash big}, etc.)} The \verb`\left` and \verb`\right` modifiers and also the series of \verb`\big...` modifiers\texttt{ }(\texttt{\textbackslash}\verb`bigl \bigr`; \verb`\Bigl \Bigr`; \verb`\biggl \biggr`; \verb`\Biggl \Biggr`) are available for use with all brackets (parentheses, square brackets, braces). If you feel \verb`\left`, \verb`\right` give too much space around your formulas, you can use \verb`\mleft`, \verb`\mright` from the \texttt{mleftright} package. \begin{verbatim} \eval[p=.,ff]{\[ \exp\left( \dfrac{\ln2}{4}+\dfrac{\ln8}{4} \right), \exp\mleft( \dfrac{\ln2}{4}+\dfrac{\ln8}{4} \mright)\]} \end{verbatim} $\Longrightarrow$ \eval[p=.,ff]{\[ \exp\left( \dfrac{\ln2}{4}+\dfrac{\ln8}{4} \right), \exp\mleft( \dfrac{\ln2}{4}+\dfrac{\ln8}{4} \mright) \]}\texttt{numerica} also accepts the use of left-right modifiers with \verb`.` (dot) and with \verb`/`, but if parentheses are not wanted it can be simpler just to use a \verb`\big` command: \begin{centred} \verb`\eval[p=.]{\[ \dfrac{3+4}{2+1}\bigg/\dfrac{1+2}{4+5} \]}` $\Longrightarrow$ \eval[p=.]{\[ \dfrac{3+4}{2+1}\bigg/\dfrac{1+2}{4+5} \]} \end{centred} Modifiers with their accompanying brackets etc.\,can be nested. \section{Unary functions} The unary functions catered for in \texttt{numerica} (at present) are the trigonometric and hyperbolic functions, the various logarithms, the exponential function, and the signum function. Mathematicians delimit the arguments of these functions not only with parentheses, but also with square brackets and (mathematical) braces (\verb`\{ \}`). In \LaTeX{} these are available both in explicit character form and also in the command form of §\ref{subsec:calcCommandBrackets}. Of whatever kind, brackets can be qualified with \verb`\left \right`, \verb`\bigl \bigr`, etc., and \verb`\mleft` and \verb`\mright` from the \texttt{mleftright} package. \subsection{Trigonometric functions} \label{subsec:calcTrigonometricFunctions}\LaTeX{} provides all six trignometric functions, \verb`\sin`, \verb`\cos`, \verb`\tan`, \verb`\csc`, \verb`\sec`, \verb`\cot`. Their arguments are assumed to be in radians unless degrees are explicitly ordered, either by entering \verb`o` (lowercase letter `o', reminiscent of a degree symbol) in the settings option, or by appending \verb`\degree` to a number. The command \verb`\degree` is defined in \texttt{numerica} (using \verb`\ProvideDocumentCommand`) and expands to $\degree$ in both text and math modes.) \begin{centred} \verb`\eval{$ \sin(\pi/3) $}` $\Longrightarrow$ \eval{$ \sin(\pi/3) $}, \verb`\eval[o]{$ \sin 60 $}` $\Longrightarrow$ \eval[o]{$ \sin 60 $}, \verb`\eval{$ \sin 60\degree $}` $\Longrightarrow$ \eval{$ \sin 60\degree $}. \end{centred} \noindent\LaTeX{} also provides the three main trigonometric inverses: \verb`\arcsin`, \verb`\arccos`, \verb`\arctan`. The three missing inverses – \verb`\arccsc`, \verb`\arcsec`, \verb`\arccot` – are provided by \texttt{numerica}. In the example, the \verb`p` setting has been used to attach a degree symbol to the answer: \begin{centred} \verb`\eval[p=\degree]{$ (\arccot 1)/1\deg $}` $\Longrightarrow$ \eval[p=\degree]{$ (\arccot 1)/1\deg $}. \end{centred} Alternatively, you can manually append a \verb`\degree` command after the \verb`\eval` command. Repeating the last example, everything is clearer if the \verb`o` option is used: \begin{centred} \verb`\eval[o]{$ \arccot 1 $}\degree` $\Longrightarrow$ \eval[o]{$\arccot1 $}\degree. \end{centred} Inverses can also be constructed using the `$-1$' superscript notation. Thus \begin{centred} \verb`\eval[p=\degree,o]{$ \sin^{-1}(1/\surd2) $}` $\Longrightarrow$ \eval[p=\degree,o]{$ \sin^{-1}(1/\surd2) $}. \end{centred} \subsubsection{Complicated arguments} \label{subsec:calcComplicated-arguments}A general function $f$ of $x$ is usually written $f(x)$: the argument of the function is delimited by parentheses. In practice, with familiar functions, mathematicians often don't bother with the parentheses, even when the argument includes more than one factor: $\sin\tfrac{1}{2}\pi$, $\cos2\pi t$, $\ln xy$ ($=\ln x+\ln y$), and so on. So long as the argument is composed of numbers, constants, variables or \verb`\tfrac`-s or \verb`\sfrac`-s, \texttt{numerica} parses the argument without difficulty and without requiring parentheses to be inserted. As function arguments become more complicated, parentheses can become necessary to clarify just what expression the function is acting on. But trigonometric identities like \[ \sin A+\sin B=2\sin\tfrac{1}{2}(A+B)\cos\tfrac{1}{2}(A-B) \] and especially Fourier series where expressions like \[ \cos\frac{2\pi}{T}nt,\quad\cos\frac{2\pi}{T}n(t+\tfrac{1}{2}T),\quad\text{\ensuremath{\sin(N+\tfrac{1}{2})\frac{2\pi\tau}{T}}, } \] \[ \sin2\pi\left(\frac{x}{\lambda}-\frac{t}{T}\right),\quad\sin(n+\tfrac{1}{2})(x-t), \] are a common occurrence, show that in practice parentheses that enclose the whole argument, even for complicated expressions, are often omitted. Context makes clear where the function argument ends and mathematicians read the expressions accordingly. What should \texttt{numerica} do? Insist that the whole argument be parenthesized? But that results in expressions that are generally less pleasing to the eye and require more concentration to read, to disentangle the enclosing from the enclosed parentheses: \[ \sin\left(\tfrac{1}{2}(A+B)\right),\quad\sin\left(2\pi\left(\frac{x}{\lambda}-\frac{t}{T}\right)\right),\quad\sin\left((n+\tfrac{1}{2})(x-t)\right). \] Admittedly square brackets and mathematical braces can help here, but mathematicians don't (generally) do this. The examples above are culled from a number of different texts that I had to hand – I didn't need to go searching for them. To insist that formulas be written in a `forced' or pedantic way, goes against the underlying idea behind \texttt{numerica}: to evaluate expressions in the form in which they are typeset.\texttt{ } Rather, from version 3.0.0 the recommended way of handling such expressions is to put the \emph{whole} argument of the function between \LaTeX{} braces. (This applies not only to the trigonometric functions but also to \emph{any} unary function.) Yes, inserting \LaTeX{} braces does involve modifying the formula, but it fits naturally within \LaTeX{} practice and, crucially, it makes \emph{no change} to the \texttt{pdf} display. The formula retains its `natural' appearance at the same time as the full argument is delimited so that \texttt{numerica} knows what to operate on. Thus \begin{centred} \verb`\eval{$ \sin{\tfrac16(m+n)\pi} $}[m=1,n=2]`, $\Longrightarrow$ \eval{$ \sin{\tfrac16(m+n)\pi} $}[m=1,n=2], \end{centred} which is $\sin\tfrac{1}{2}\pi$, and \begin{verbatim} \eval{\[ \sin{2\pi\mleft(\frac{x}{\lambda} -\frac{t}{T}\mright)} \]}[x=1,\lambda=2,t=3,T=4] \end{verbatim} $\Longrightarrow$ \eval{\[ \sin{2\pi\mleft(\frac{x}{\lambda} -\frac{t}{T}\mright)} \]}[x=1,\lambda=2,t=3,T=4] \noindent which is the sine of $-\tfrac{1}{2}\pi=2\pi\times(-\tfrac{1}{4})$. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% In earlier versions of \texttt{numerica} there was a setting \texttt{()=0}, \texttt{1}, \texttt{2} (see Chapter~\ref{chap:settingsSettings} for a discussion of settings) which changed the way parentheses were parsed and allowed (most of) these usages. But it was difficult to document and remember exactly what was and was not allowed at each setting value, meaning the result of a calculation might not reflect what a user intended. Besides, dealing with the different setting values complicated the code. From version 3.0.0, with the use of braces to delimit such arguments, this setting has been withdrawn and now produces a \texttt{numerica} error message. The use of \LaTeX{} braces to delimit the arguments of \emph{mathematical} functions\emph{ }is more generally discussed at §\ref{subsec:evalBraced-groups}.\end{shaded}% \end{minipage} \subsection{Hyperbolic functions} Four of the six hyperbolic functions: \verb`\sinh`, \verb`\cosh`, \verb`\tanh`, and \verb`\coth` are provided by \LaTeX , and \emph{no} inverses. \texttt{numerica} fills the gaps, providing the missing hyperbolic functions, \verb`\csch` and \verb`\sech`, and all missing inverses. There is no agreed notation in common use for the hyperbolic inverses. \emph{HMF} writes arcsinh, arccosh, \ldots , ISO recommends arsinh, arcosh, \ldots , \texttt{l3fp} uses asinh, acosh, \ldots{} as do the computer algebra system \texttt{maxima} and the spreadsheet \texttt{LibreOffice Calc}. \texttt{numerica} makes no attempt to decide the issue. From version 3.0.0, it accepts all\emph{ }three forms for all six functions. All can be used within an \verb`\eval` command: \begin{verbatim} \eval[pp,p=.,ff]{\[ \atanh\tanh 3, \sinh\arsinh 3, \arcsech\sech 3 \]} \end{verbatim} $\Longrightarrow$ \eval[pp,p=.,ff]{\[ \atanh\tanh 3, \sinh\arsinh 3, \arcsech\sech 3 \]}As for the trig.\ inverses, hyperbolic inverses can also be constructed using the `$-1$' superscript notation. Thus \begin{centred} \verb`\eval{$ \coth\coth^{-1}1.5 $}` $\Longrightarrow$ \eval{$ \coth\coth^{-1}1.5 $}. \end{centred} \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \subsubsection{Absence from \texttt{l3fp}} Please note that \texttt{l3fp} does not (as yet) provide \emph{any} hyperbolic functions natively. The values \texttt{numerica} provides for these functions are \emph{calculated} values using familiar formulas involving exponentials (for the direct functions) and natural logarithms and square roots for the inverses. Rounding errors mean the values calculated may not have $16$-figure accuracy. The worst `offenders' are likely to be the least used, \verb`\acsch` and \verb`\asech`. For instance, \[ \acsch x=\ln\left[\frac{1}{x}+\left(\frac{1}{x^{2}}+1\right)^{\mkern-6mu 1/2}\right], \] \begin{centred} \verb`\eval{$ \csch \acsch 7 $}[15]` $\Longrightarrow$ \eval{$ \csch \acsch 7 $}[15]. \end{centred} \end{shaded}% \end{minipage} \subsection{Logarithms} The natural logarithm \verb`\ln`, base $10$ logarithm \verb`\lg`, and binary or base $2$ logarithm \verb`\lb` are all recognized, as is \verb`\log`, preferably with a subscripted base: \begin{centred} \verb`\eval{$ \log_{12}1728 $}` $\Longrightarrow$ \eval{$ \log_{12}1728 $} \end{centred} If there is no base indicated, base $10$ is assumed. (The notations \verb`\ln`, \verb`\lg`, and \verb`\lb` follow ISO 80000-2 recommendation, which frowns upon the use of the unsubscripted \verb`\log` although only \verb`\ln` appears to be widely used.) The base need not be explicitly entered as a number. It could be entered as an expression or be specified in the vv-list: \begin{centred} \verb`\eval*{$ \log_b c $}[b=2,c=1024]` $\Longrightarrow$ \eval*{$ \log_b c $}[b=2,c=1024], \end{centred} the log to base $2$ in this case. It is possible to use the unadorned \verb`\log` with a base different from $10$; see §\ref{subsec:settingsLogBase}. \subsection{Other unary functions} Other unary functions supported are the exponential function \verb`\exp`, and signum function \verb`\sgn`, equal to $1$, $-1$, or $0$, depending as its argument is positive, negative or zero. \begin{verbatim} \eval{$ \sgn(\exp(x)-e^x) $}[x=1],\quad \eval{$ \sgn(e^x-\exp(x)) $}[x=2]. \end{verbatim} $\Longrightarrow$ \eval{$ \sgn(\exp(x)-e^x) $}[x=1],\quad \eval{$ \sgn(e^x-\exp(x)) $}[x=2]. The first of these is expected, the second probably not. $\exp x$ is provided by \texttt{l3fp}, a built-in function; $e^{x}$ is calculated by \texttt{numerica}, a number ($e$) raised to a power. They differ by $1$ in the $15$-th decimal place: \begin{centred} \verb`\eval[ff]{$ \exp 2, e^2 $}[15*]` $\Longrightarrow$ \eval[ff]{$ \exp 2, e^2 $}[15*]. \end{centred} \subsection{Squaring, cubing, \ldots{} unary functions} \label{subsec:calcSquaring-etc-unary}\verb`\eval` happily digests a familiar but `incorrectly formed' expression like \[ \sin^{2}1.234+\cos^{2}1.234. \] You do not have to parenthesize like $(\sin1.234)^{2}+(\cos1.234)^{2}$ or (heaven forbid) $(\sin(1.234))^{2}+(\cos(1.234))^{2}$; the everyday usage is fine: \begin{centred} \verb`\eval{$ \sin^2\theta+\cos^2\theta $}[\theta=1.234]` $\Longrightarrow$ \eval{$ \sin^2\theta+\cos^2\theta $}[\theta=1.234] . \end{centred} Equally \verb`\eval` has no difficulty reading the `correct' pedantic form \begin{centred} \verb`\eval{$ (\sin(\theta))^2+(\cos(\theta))^2 $}[\theta=1.234]` $\Longrightarrow$ \eval{$ (\sin(\theta))^2+(\cos(\theta))^2 $}[\theta=1.234] . \end{centred} A hyperbolic identity is corroborated in this example: \begin{centred} \verb`\eval[ff]{\[ \sinh 3x, 3\sinh x+4\sinh^3x \]}[x=1]` $\Longrightarrow$ \eval[ff]{\[ \sinh 3x, 3\sinh x+4\sinh^3x \]}[x=1] \end{centred} In fact all named unary functions in \texttt{numerica} can be squared, cubed, etc., in this `incorrect' but familiar way, although the practice outside the trigonometric and hyperbolic contexts seems rare. When the argument of the function is parenthesized and raised to a power – like $\sin(\pi)^{2}$ – it is read by \verb`\eval` as the `sine of the square of pi', $\sin(\pi^{2})$, and \emph{not }as the `square of the sine of pi', $(\sin\pi)^{2}$: \begin{centred} \verb`\eval{$ \sin(\pi)^2 $}` $\Longrightarrow$ \eval{$ \sin(\pi)^2 $} . \end{centred} Things are done like this in \texttt{numerica} above all to handle the logarithm in a natural way. Surely (see \emph{HMF} 4.1.11) $\ln x^{n}=n\ln x$? I.e.\ $\ln x^{n}=\ln(x^{n})$ rather than $(\ln x)^{n}$. And if we wish to write (as we do) $\ln(1+1/n)^{n}=n\ln(1+1/n)=1-1/2n+1/3n^{2}-\ldots$ to study the limiting behaviour of $(1+1/n)^{n}$, then we are committed to $\ln(x)^{n}=n\ln(x)=\ln(x^{n})$ too. \section{\emph{n}-ary functions} \label{sec:calc-n-ary-functions}The functions of more than one variable ($n$-ary functions) that \texttt{numerica} supports are \verb`\max`, \verb`\min` and \verb`\gcd`, greatest common divisor. The comma list of arguments (semicolon list if the \verb`comma` package option has been used) to \verb`\max`, \verb`\min` or \verb`\gcd` can be of arbitrary length. The arguments themselves can be expressions or numbers. As implemented in \texttt{numerica}, for \verb`\gcd` non-integer arguments are\emph{ }rounded to integers. Hence both $y$ and $3y$ are independently rounded in the following example – to $81$ and $243$ respectively: \begin{centred} \verb`\eval{$ \gcd(12,10x^2,3y,y,63) $}[y=1/0.0123456789,x=3]` $\Longrightarrow$ $\vsp$\eval{$ \gcd(12,10x^2,3y,y,63) $}[y=1/0.0123456789,x=3]. \end{centred} The rounding occurs within the greatest common divisor routine, not in the vv-list; the variable retains its original value. Modifying the example, this becomes evident in the sixth decimal place of the new result: \begin{centred} \verb`\eval{$ \gcd(12,10x^2,3y,y,63) + y $}[y=1/0.0123456789,x=3]` $\Longrightarrow$ $\vsp$\eval{$ \gcd(12,10x^2,3y,y,63) + y $}[y=1/0.0123456789,x=3]. \end{centred} For $n$-ary functions, squaring, cubing, etc. follow a different pattern from that for unary functions. The argument of these functions is a comma list. Squaring it makes no sense and we understand the superscript as applying to the function as a whole. (Consistency is not the point here; it is how a person reads the expression that \texttt{numerica} tries to accommodate.) \begin{centred} \verb`\eval{$ \gcd(3x,x,\arcsin 1/\deg)^2 $}[x=24]` $\Longrightarrow$ $\vsp$\eval{$ \gcd(3x,x,\arcsin 1/\deg)^2$}[x=24] . \end{centred} \section{Absolute value, floor \& ceiling functions} \label{sec:calcAbsValueEtc}It is tempting to use the \textsf{|} key on the keyboard for inserting an absolute value sign. \texttt{numerica} accepts this usage, but it is strongly deprecated. The spacing is incorrect – compare $|-l|$ using \textsf{|}, against $\lvert-l\rvert$ using \verb`\lvert \rvert`. Also, with\textsf{ |}, the identity of the left and right delimiters makes parsing nested absolute values difficult. \texttt{numerica} does not attempt to do so. \verb`\lvert \rvert` are better in every way except ease of writing.\texttt{ }To aid such ease \texttt{numerica }provides the \verb`\abs` function (using the \texttt{\textbackslash DeclarePairedDelimiter} command of the \texttt{mathtools} package). This takes a mutually exclusive star (asterisk) or square bracketed optional argument, and a mandatory braced argument. The starred form wraps \verb`\left\lvert`, \verb`\right\rvert` around the mandatory argument: \begin{centred} \verb`\eval[p=.]{\[ 3\abs*{\frac{\abs{n}}{21}-1} \]}[n=-7]` $\Longrightarrow$ \eval[p=.]{\[ 3\abs*{\frac{\abs{n}}{21}-1} \]}[n=-7] \end{centred} The optional argument provides access to the \verb`\big...` modifiers: \begin{verbatim} \eval[p=.]{\[ \abs[\Big]{\abs{a-c}-\abs[\big]{A-C}} \]}[A=12,a=-10,C=7,c=-5] \end{verbatim} $\Longrightarrow$ \eval[p=.]{\[ \abs[\Big]{\abs{a-c}-\abs[\big]{A-C}} \]}[A=12,a=-10,C=7,c=-5] \noindent The form without either option dispenses with modifiers altogether: \begin{centred} \verb`\eval{$ \tfrac12(x+y)+\tfrac12\abs{x-y} $}[x=-3,y=7].` $\Longrightarrow$ \eval{$ \tfrac12(x+y)+\tfrac12\abs{x-y} $}[x=-3,y=7]. \end{centred} As noted, the star and square bracket options are mutually exclusive. \texttt{numerica} also provides the functions \verb`\floor` and \verb`\ceil`, defined in the same way, taking a mutually exclusive star or square bracketed optional argument, the starred forms wrapping \verb`\left\lfloor`, \verb`\right\rfloor` or \verb`\left\lceil`, \verb`\right\rceil` around the mandatory argument, and the square bracket option forms replacing the \verb`\left` and \verb`\right` with the corresponding \verb`\big` commands (see the \verb`\abs` example above). The form without star or square-bracket option dispenses with any modifier at all. \begin{centred} \verb`\eval[pp,ff]{$ \floor{-\pi}, \ceil{\pi} $}` $\Longrightarrow$ \eval[pp,ff]{$ \floor{-\pi}, \ceil{\pi} $}. \end{centred} The floor function, $\lfloor x\rfloor$, is the greatest integer $\le x$; the ceiling function, $\lceil x\rceil$ is the smallest integer $\ge x$. Like the absolute value, the floor and ceiling functions, can be nested: \begin{centred} \verb`\eval{$ \floor{-\pi+\ceil{e}} $}` $\Longrightarrow$ \eval{$ \floor{-\pi+\ceil{e}} $}. \end{centred} \subsection{Squaring, cubing, \ldots{} absolute values, etc.} These three functions can be raised to a power \emph{without} extra parentheses: \begin{centred} \verb`\eval[pp,ff]{$ \ceil{e}^2, \floor{e}^2 $}` $\Longrightarrow$ \eval[pp,ff]{$ \ceil{e}^2, \floor{e}^2 $},\medskip{} \verb`\eval{$ \abs{-4}^2 $}` $\Longrightarrow$ \eval{$ \abs{-4}^2 $}. \end{centred} \section{Factorials, binomial coefficients} \label{sec:calcFactorialsBinom}Factorials use the familiar trailing \texttt{!} notation: \begin{centred} \verb`\eval{$ 7! $}` $\Longrightarrow$ \eval{$ 7! $}, \verb`\eval{$ (\alpha+\beta)!-\alpha!-\beta! $}[\alpha=2,\beta=3]` $\Longrightarrow$ \eval{$ (\alpha+\beta)!-\alpha!-\beta! $}[\alpha=2,\beta=3]. \end{centred} The examples illustrate how \texttt{numerica} interprets the argument of the factorial symbol: it `digests' \begin{itemize} \item a preceding (possibly multi-digit) integer, or \item a preceding variable, or \item a bracketed expression, or \item a bracket-like expression. \end{itemize} A bracket-like expression is an absolute value, floor or ceiling function, since they delimit arguments in a bracket-like way: \begin{centred} \verb`\eval{$ \abs{-4}!+\floor{\pi}!+\ceil{e}! $}` $\Longrightarrow$ \eval{$ \abs{-4}!+\floor{\pi}!+\ceil{e}! $}. \end{centred} The result of feeding the factorial an expression different in kind from one of these four cases may give an error message or an unexpected result. Use parentheses around such an expression; for example write $(3^{2})!$, rather than $3^{2}!$. Nesting of brackets for factorials is accepted: \begin{centred} \verb`\eval{$ ((5-2)!+1)! $}` $\Longrightarrow$ \eval{$ ((5-2)!+1)! $}. \end{centred} The factorials of negative integers are not defined and raise a \texttt{numerica} error. It simplifies the code to treat the factorial of a positive non-integer as the factorial of the integer it rounds to, rather than raising an error. For the sake of the reader, in such circumstances, an author should make the rounding explicit: \begin{centred} \verb`\eval{$ \floor{\pi}! $}` $\Longrightarrow$\eval{$ \floor{\pi}! $}. \end{centred} This rounding to an integer is different from the behaviour in earlier versions of \texttt{numerica} but should make no noticeable difference. \subsection{Double factorials} The double factorial, written $n!!,$ is the product $n(n-2)(n-4)\ldots\times4\times2$ when $n$ is even, and the product $n(n-2)(n-4)\ldots\times3\times1$ when $n$ is odd: \begin{centred} \verb`$\eval[pp,ff]{6!!, 5!!}$` $\Longrightarrow$ $\eval[pp,ff]{6!!, 5!!}$. \end{centred} As with factorials, the double factorial sign can be appended to a (possibly multi-digit) number, a variable, a bracketed expression or a bracket-like expression. \begin{centred} \verb`\eval[env=\[,ff]{ n!!, (n-1)!!, \abs{2-n}!! }[n=\sqrt{49}]` $\Longrightarrow$ \eval[env=\[,ff]{ n!!, (n-1)!!, \abs{2-n}!! }[n=\sqrt{49}] \end{centred} Since $n!=n!!(n-1)!!$, \[ n!!=\frac{n!}{(n-1)!!}=\frac{(n+1)!}{(n+1)!!}, \] on multiplying top and bottom by $n+1$. Putting $n=0$ in the left and right expressions shows that $0!!=1$. Now put $n=0$ in the left and middle expressions. We deduce that $(-1)!!=1$. It follows that double factorials are defined for integers $\ge-1$. \subsection{Binomial coefficients} Binomial coefficients are entered in \LaTeX{} with the \verb`\binom`\textbf{ }command. It takes two arguments, \verb`\binom{a}{b}` and scales like \verb`\frac`: inline it displays as $\binom{a}{b}$, and in displaystyle as \[ \binom{a}{b}. \] One can force textstyle with \verb`\tbinom` and force displaystyle with \verb`\dbinom`. As implemented in \texttt{numerica}, these are \emph{generalised} binomial coefficients: \[ \binom{x}{k}=\frac{x(x-1)\dots(x-k+1)}{k(k-1)\dots1},\quad(x\in\mathbb{R},~k\in\mathbb{N}), \] where $x$ need not be a positive or zero integer, and where $\binom{x}{0}=1$ by definition. \begin{centred} \verb`\eval[pp,p=.,ff]{$ \tbinom53, \tbinom70 $}` $\Longrightarrow$ \eval[pp,p=.,ff]{$ \tbinom53, \tbinom70 $} \end{centred} The first (or upper) argument can be any real number; it does not need to be an integer or positive: recalling that \eval[eq=\approx]{$\pi^2$}[3], \begin{centred} \verb`\eval[pp,p=.,ff]{$ \tbinom94, \tbinom{\pi^2}4, \tbinom{10}4 $}[3]`$\Longrightarrow$ \eval[pp,p=.,ff]{$ \tbinom94, \tbinom{\pi^2}4, \tbinom{10}4 $}[3] \end{centred} If the second (or lower) argument of \verb`\binom` is negative, \texttt{numerica} responds with a message: \begin{centred} \verb`\eval{$ \binom 5{-3} $}` $\Longrightarrow$ \eval{$ \binom 5{-3} $}. \end{centred} If the second argument is positive but not an integer, \texttt{numerica} rounds it to the nearest integer before calculating the binomial coefficient: \begin{centred} \verb`\eval[pp,ff]{$ \binom 5e, \binom 53 $}` $\Longrightarrow$ \eval[pp,ff]{$ \binom 5e, \binom 53 $}. \end{centred} This differs from previous versions of \texttt{numerica} which would raise an error in this case. Although positive non-integers are now rounded to the nearest integer, out of consideration for the reader, an author should make explicit the fact that an integer has been used. In the example I should have written \verb`\ceil{e}` rather than \verb`e`. \section{Sums and products} \texttt{numerica} recognizes \verb`\sum`, displaying as $\sum$, and \verb`\prod`, displaying as $\prod$, and expects both symbols to have lower and upper summation or product limits specified. The lower limit must be given in the form\emph{ variable=initial value} where \emph{variable} is the summation or product variable; the upper limit requires only the final value to be specified (although it can also be given in the form \emph{variable=final value}). The values may be expressions depending on other variables and values, and are rounded to integers. This differs from earlier versions of \texttt{numerica} where, if the result of a calculation differed too much from an integer, it prompted an error message. Now the rounding happens automatically, whatever the value. As in other similar contexts, for the sake of the reader an author should ensure that the integer value is explicit: \begin{centred} \verb`\eval[p]{\[ \sum_{n=\floor{\pi/e}}^{\ceil{\pi e}}n \]}` $\Longrightarrow$\eval[p]{\[ \sum_{n=\floor{\pi/e}}^{\ceil{\pi e}}n \]} \end{centred} \noindent (which is $\sum_{n=1}^{9}n$).\emph{ }If the upper limit is less than the lower limit the result is zero. Notice that there is no vv-list. The summation variable does not need to be included there unless there are other variables that depend on it. However, in the case \begin{centred} \verb`\eval[p]{\[ \sum_{k=1}^N\frac1{k^3} \]}[N=100][4]` $\Longrightarrow$ \eval[p]{\[ \sum_{k=1}^N\frac1{k^3} \]}[N=100][4] \end{centred} the upper limit $N$ is necessarily assigned a value in the vv-list. To the author it seems natural to enter the lower limit first, immediately after the \verb`\sum` command (the sum is \emph{from }something \emph{to} something), but no problem will accrue if the upper limit is placed first (after all, the appearance of the formula in the \texttt{pdf} is the same): \begin{centred} \verb`\eval[p=.]{\[ \sum^N_{k=1}\frac1{k^3} \]}[N=100][4]` $\Longrightarrow$ \eval[p=.]{\[ \sum^N_{k=1}\frac1{k^3} \]}[N=100][4] \end{centred} Another example of a sum, using binomial coefficients this time, is \begin{centred} \verb`\eval[p]{\[ \sum_{m=0}^5\binom{5}{m}x^m y^{5-m} \]}[x=0.75,y=2.25]` $\Longrightarrow$ \eval[p]{\[ \sum_{m=0}^5\binom{5}{m}x^m y^{5-m} \]}[x=0.75,y=2.25] \end{centred} which is just \begin{centred} \verb`\eval{$(x+y)^5$}[x=0.75,y=2.25]` $\Longrightarrow$ \eval{$ (x+y)^5 $}[x=0.75,y=2.25], \end{centred} or $3^{5}$. Now let's calculate a product: \begin{verbatim} \eval[p]{\[ \prod_{k=1}^{100} \biggl(\frac{x^2}{k^2\pi^2} +1\biggr) \]}[x=1][3] \end{verbatim} $\Longrightarrow$ \eval[p]{\[\prod_{k=1}^{100} \biggl(\frac{x^2}{k^2\pi^2} +1\biggr)\]}[x=1][3] \noindent to be compared with \verb`\eval{$ \sinh 1 $}[3]` $\Longrightarrow$ \eval{$ \sinh1 $}[3]. Obviously more terms than $100$ are required in the product to achieve 3-figure accuracy. \subsection{Infinite sums and products} How many more? Let's `go the whole hog' and put $\infty$ in the upper limit of this product: \begin{verbatim} \eval[p=.]{\[ \prod_{k=1}^{\infty} \biggl(\frac{x^2}{k^2\pi^2} +1\biggr) \]}[x=1][3] \end{verbatim} $\Longrightarrow$ \eval[p=.] {\[ \prod_{k=1}^{\infty} \biggl(\frac{x^2}{k^2\pi^2} +1\biggr) \]}[x=1][3] \noindent Disappointingly, we still get the same result, deficient by $1$ in the third decimal place. Obviously \texttt{numerica} has not multiplied an infinite number of terms and, just as obviously, the finite number of terms it \emph{has} multiplied are too few. How \texttt{numerica} decides when to stop evaluating additional terms in an infinite sum or product is discussed below in §\ref{sec:calcStoppingCriterion}. For this particular product the problem is that it converges slowly. Any criterion for when to stop multiplying terms or, for an infinite sum adding terms, seems bound to fail whenever convergence is sufficiently slow. Presumably any stopping criterion must measure smallness in some way. But terms of the divergent harmonic series $\sum(1/n)$, for example, can always be found smaller than any value we care to specify. It is not surprising that a stopping criterion will fail when convergence is slow enough. However, the default criterion can be changed: again, see below in §\ref{sec:calcStoppingCriterion}. Other infinite sums converge more rapidly, and the default settings work admirably for them. For example \begin{centred} \verb`\eval{$ (1+0.1234)^{4.321} $}` $\Longrightarrow$ \eval{$ (1+0.1234)^{4.321} $}. \end{centred} Using binomial coefficients we can express this as an infinite sum:\medskip{} \begin{verbatim} \eval[p=.]{\[ \sum_{n=0}^{\infty}\binom{\alpha}{n}x^{n} \]}[\alpha=4.321,x=0.1234] \end{verbatim} $\Longrightarrow$ \eval[p=.] {\[ \sum_{n=0}^{\infty}\binom{\alpha}{n}x^{n} \]}[\alpha=4.321,x=0.1234] \subsection{The stopping criterion} \label{sec:calcStoppingCriterion}There are ways of tweaking various parameters to nudge infinite sums and products to a correct limit. These tweaks are applied via the settings option of the \verb`\eval` command. The normal convergence criterion used by \texttt{numerica} to determine when to stop adding/multiplying terms in an infinite sum/product is \emph{when the next term added/multiplied leaves the total unaltered when rounded to 2 more digits than the specified rounding value.} Suppose $L_{k}$ is the partial sum/product after $k$ terms, and $r$ is the rounding value.\footnote{E.g.\ if $T(n)$ is the $n$-th term then the partial sum $L_{k}=\sum_{n=1}^{k}T(n)$.} Let $\left(L_{k}\right)_{r}$ denote $L_{k}$ rounded to $r$ figures. \emph{The infinite sum or product stops at the $(k+1)$-th term (and the value is attained at the $k$-th term) when }$\left(L_{k+1}\right)_{r+2}=\left(L_{k}\right)_{r+2}$. The hope is that if this is true at rounding value $r+2$ then at rounding value $r$ the series or product will have attained a stable value at that smaller rounding value. For a series of monotonic terms converging quickly to a limit, this stopping criterion works well, less so if convergence is slower, as seen earlier with the infinite product for $\sinh1$. The criterion can fail completely when terms behave in a non-monotonic manner. Terms of a Fourier series, for example, may take zero values so that $L_{k+1}=L_{k}$ and, \emph{a fortiori}, $\left(L_{k+1}\right)_{r+2}=\left(L_{k}\right)_{r+2}$; the criterion is necessarily satisfied but the series may still be far from its limit. In a product the equivalent would be a term taking unit value. Sometimes the initial terms of series or products are `irregular' and take these `stopping' values meaning sum or product would stop after only one or two additions/multiplications and far from any limit. \begin{table}[t] \centering \centering{}\caption{Stopping criterion settings}\label{tab:calcStoppingCriterionSettings} \begin{center} {\small{}% \begin{tabular}{ll>{\raggedright}p{6cm}l} \toprule {\small key} & {\small type} & {\small meaning} & {\small default}\tabularnewline \midrule {\small\texttt{S+}} & {\small int} & {\small extra rounding for sums} & {\small\texttt{2}}\tabularnewline {\small\texttt{S?}} & {\small$\text{int}\ge0$} & {\small number of query terms for sums} & {\small\texttt{0}}\tabularnewline {\small\texttt{P+}} & {\small int} & {\small extra rounding for products} & {\small\texttt{2}}\tabularnewline {\small\texttt{P?}} & {\small$\text{int}\ge0$} & {\small number of query terms for products} & {\small\texttt{0}}\tabularnewline \bottomrule \end{tabular}} \par\end{center} \end{table} To cope with these possibilities, \texttt{numerica} offers two settings for sums, two for products, summarized in Table~\ref{tab:calcStoppingCriterionSettings}. These are entered in the settings option of the \verb`\eval` command. \begin{itemize} \item \texttt{S+=} \texttt{(P+=)\quad{}} \emph{additional} rounding on top of the specified (or default) rounding for the calculation; the larger \texttt{} is, the more likely that sum or product has attained a stable value at the specified rounding value $r$; default = $2$ \item \texttt{S?= $\ge0$ (P?= $\ge0$)\quad{}}the number of terms to \emph{query} after the stopping criterion has been achieved to confirm that it is not an `accident' of particular values; default = $0$ \begin{itemize} \item once the stopping criterion has been met, we add/multiply these next few terms to the result and check at each step whether the result is unchanged at the specified rounding value. Suppose the additional rounding (\texttt{S+} or \texttt{P+}) is $\delta r$ on top of the specified rounding $r$ and let the number of query terms be $q$. (By default $\delta r=2$ and $q=0$.) Suppose $L_{k_{0}}$ is the first term at which the stopping criterion is achieved. That means $\left(L_{k_{0}}\right)_{r+\delta r}=\left(L_{k_{0}+1}\right)_{r+\delta r}$. What we require of the query terms is that $\left(L_{k_{0}}\right)_{r+\delta r}=\left(L_{k_{0}+1+j}\right)_{r+\delta r}$ for $j=0,1,\ldots,q$. \end{itemize} \end{itemize} Earlier we found that the infinite product for $\sinh1$ with the default settings gave the wrong value, $0.174$, deficient by $1$ in the last digit. We now have the means to tweak the stopping criterion by increasing the additional rounding: \begin{verbatim} \eval[p,P+=3]{\[ \prod_{k=1}^{\infty} \biggl(\frac{x^2}{k^2\pi^2} +1\biggr) \]}[x=1][3]\nmcInfo{prod}. \end{verbatim} \noindent$\Longrightarrow$ \noindent\eval[p,P+=3]{\[ \prod_{k=1}^{\infty} \biggl(\frac{x^2}{k^2\pi^2} +1\biggr) \]}[x=1][3]\nmcInfo{prod}. To obtain that last item of information (350 factors), I've anticipated a little and used the command \verb`\nmcInfo` with the argument \verb`prod` (see §\ref{sec:supplInfo}). The product now produces the correct three-figure value, but it takes $350$ factors to do so. Knowing how many terms or factors have been needed helps assess how trustworthy the result from an infinite sum or product is. For example, for the exponential series, \begin{verbatim} \eval[p]{\[ \sum_{k=0}^\infty \frac1{k!} \]}[9]\nmcInfo{sum}. \end{verbatim} $\Longrightarrow$ \eval[p]{\[\sum_{k=0}^\infty \frac1{k!} \]}[9]%\nmcInfo{sum}. To $9$ places of decimals, using the default value \texttt{S+=2}, the exponential series arrives at the right sum after only $15$ terms. Convergence is rapid. We can trust this result (and it is in fact the correct nine-figure value). By contrast, if we didn't know the value of $\sinh1$ beforehand, noting the number of factors required would make us justly cautious about accepting the result of the infinite product calculation. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% One way to gain confidence in a result is to choose a possibly unrealistic rounding value $r$ – say the default $6$ for the infinite product – then use \emph{negative} values for the additional rounding, \texttt{S+=-5}, \texttt{S+=-4}, \ldots{} , so that the stopping criterion applies at rounding values $s=r+S_{+}$ of $6+(-5)=1$ decimal place, $6+(-4)=2$ decimal places, and so on, but the result is always presented to $6$ decimal places. You can then see how the $6$-figure results behave relative to the number of terms it takes to meet the stopping criterion. A little experimenting shows that for the infinite product for $\sinh1$ the number of factors $N_{s}$ required at a stopping rounding value $s$ increases in geometric proportion with a scale factor of about $3$: $N_{s}\approx\text{const}\times3^{s}$. This rapidly becomes large ($3^{4}=81,3^{5}=243\dots$). For the exponential series on the other hand $N_{s}=4+s$, the number of terms increases only slowly, in direct proportion to the stopping rounding value. ~ Similar experiments with the sums of inverse fourth, third and second powers of the integers, using \verb`\nmcInfo` to find how many terms are required at each stopping rounding value, show that at least over the rounding value range $1$ to $8$, for inverse fourth powers $N_{s}\approx\text{const}\times1.7^{s}$, for inverse third powers $N_{s}\approx\text{const}\times2^{s}$ and for inverse squares $N_{s}\approx\text{const}\times3^{s}$. All are geometric rather than arithmetic progressions, but for inverse fourth powers the scale factor ($\approx1.7$) is sufficiently small that for these low values of $s$ the number of terms required does not grow too quickly (e.g.\ $1.7^6\approx\eval{1.7^6}[0]$). ~ It is a standard result (Euler) that the inverse fourth power series sums to $\pi^{4}/90$: \verb`$ \eval{ \pi^4/90 } $` $\Longrightarrow$ $ \eval{ \pi^4/90 } $ to six places, and indeed, with the default rounding value $6$ and default extra rounding \texttt{S+=2}, \begin{centred} \verb`\eval[p]{\[ \sum_{k=1}^\infty \frac1{k^4} \]}` $\Longrightarrow$ \eval[p=.]{\[ \sum_{k=1}^\infty \frac1{k^4} \]} \end{centred} \end{shaded}% \end{minipage} \subsubsection{Premature ending of infinite sums} All the series considered so far have been monotonic. Trigonometric series will generally not be so, nor even single-signed. Trigonometric sums are computationally intensive and so, for the following example, I have specified a rounding value of 2. The series \[ \sum_{n=1}^{\infty}\frac{4}{n^{2}\pi^{2}}(1-\cos n\pi)\cos2\pi nt \] is the Fourier series for the triangular wave function \textbackslash\!/\!\textbackslash\!/\!\textbackslash\!/\!\textbackslash{} \ldots{} of period 1, symmetric about the origin where it takes its maximum value 1, crossing the $t$-axis at $t=0.25$ and descending to its minimum $-1$ at $t=0.5$, before ascending to a second maximum at $t=1$ (and so on). In the interval $[0,0.5)$ the series should sum to $1-4t$. The problem is that the summand $\frac{4}{n^{2}\pi^{2}}(1-\cos n\pi)\cos2\pi nt$ vanishes both when $n$ is even and when $4nt$ is an odd integer. If $t=0.1$ then $4nt$ is never an odd integer so the summand vanishes only for $n$ even, every second term. We expect the result to be $1-4\times0.1=0.6$. \begin{verbatim} \eval[p]{\[ \sum_{n=1}^{\infty} \frac{4}{n^{2}\pi^{2}} (1-\cos n\pi)\cos2\pi nt \]}[t=0.1][2]\nmcInfo{sum}. \end{verbatim} $\Longrightarrow$ \eval[p]{\[ \sum_{n=1}^{\infty} \frac{4}{n^{2}\pi^{2}} (1-\cos n\pi)\cos2\pi nt \]}[t=0.1][2]\info{sum}. Only one term? Of course – in the second term $n=2$ is even so the term vanishes and the stopping criterion is satisfied. The way around this problem is to query terms \emph{beyond} the one where the stopping criterion is achieved, i.e.\ to set \texttt{S?} to a nonzero value. We try \texttt{S?=1}: \begin{verbatim} \eval[p,S?=1]{\[ \sum_{n=1}^{\infty} \frac{4}{n^{2}\pi^{2}} (1-\cos n\pi)\cos2\pi nt \]}[t=0.1][2]\nmcInfo{sum}. \end{verbatim} $\Longrightarrow$ \eval[p,S?=1]{\[ \sum_{n=1}^{\infty} \frac{4}{n^{2}\pi^{2}} (1-\cos n\pi)\cos2\pi nt \]}[t=0.1][2]\info{sum}. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \begin{wraptable}{o}{0.35\columnwidth}% \centering{}\vspace{-5ex} \caption{Partial sums}\label{tab:calcPartialSums} \abovetopsep=2ex % \begin{tabular}{cc} \toprule $N$ & $\Sigma$\tabularnewline \midrule $63$ & $0.6001$\tabularnewline $64$ & $0.6001$\tabularnewline $65$ & $0.5999$\tabularnewline $66$ & $0.5999$\tabularnewline $67$ & $0.5999$\tabularnewline \bottomrule \end{tabular}\end{wraptable}% Table~\ref{tab:calcPartialSums} lists the results of evaluating the partial\emph{ }sums from $n=1$ to $n=N$ for values of $N$ around $65$. Since the specified rounding value is $2$ for the calculation, the stopping criterion\emph{ }applies at a rounding value of $2+2=4$. Since $N=64$ is even, the $64$th term is zero and the sum takes the same value as for $N=63$. The $65$th term is the query term and the sum differs, so the summation continues. The $66$th term vanishes, so the stopping criterion is met. This time for the query term, the $67$th, the sum retains the same $4$-figure value, and the summation \end{shaded}% \end{minipage} \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% stops. The result was attained at the $65$th term. Should we be confident in the result? Increase the number of query terms to $3$ (there is no point in increasing \texttt{S?} to $2$ because of the vanishing of the even terms); the sum stops after $113$ terms, with the same $0.6$ result.\end{shaded}% \end{minipage}\medskip{} For a final example, consider the error function \[ \erf z=\dfrac{2}{\sqrt{\pi}}\int_{0}^{z}e^{-t^{2}}dt \] which can also be rendered as an infinite sum (\emph{HMF }7.1.5): \[ \erf z=\sum_{n=0}^{\infty}(-1)^{n}\frac{z^{2n+1}}{n!\,(2n+1)}. \] (\verb`\erf` expanding to \verb`erf` has been defined in the preamble to this document using \verb`\DeclareMathOperator`.) We calculate this sum when $z=2$ to $10$ places of decimals. Although this is an alternating series, it is obvious that the summand never vanishes when $z\ne0$ as here. Hence there seems no need to change the default value \texttt{S?=0}. \begin{verbatim} \eval[p]{\[ \frac2{\sqrt{\pi}} \sum_{n=0}^\infty(-1)^n \frac{z^{2n+1}}{n!\,(2n+1)} \]}[z=2][10*]\nmcInfo{sum}. \end{verbatim} $\Longrightarrow$ \eval[p]{\[ \frac2{\sqrt{\pi}} \sum_{n=0}^\infty(-1)^n \frac{z^{2n+1}}{n!\,(2n+1)} \]}[z=2][10*]\nmcInfo{sum}. According to \emph{HMF }Table 7.1, this calculated value of $\erf2$ is correct to all $10$ places. But beyond $z=2$ errors will begin to interfere with the result. Note that $26$ terms means $n=26$ was the last value of $n$ for which the summand was evaluated. (The sum stops at the $26$th term, $n=25$, but the next term $n=26$ needs to be calculated for the stopping criterion.) Fortuitously, $2^{2\times26+1}=2^{53}$ is the greatest power of $2$ that can be \emph{exactly} rendered to the $16$ significant figures that \texttt{l3fp} uses. But $n!$ exceeds the $16$-significant figure limit of \texttt{l3fp} when $n>21$, so despite the 10-figure result, errors have already begun to occur in the denominator of the summand and accrue in the sum when $z=2$. For larger $z$ values the errors can only get worse and at some point will render the calculated value worthless at any meaningful rounding value. For example, when $z=7$ the sum apparently `evaluates' to over $929$ whereas we know that \[ \erf z<\dfrac{2}{\sqrt{\pi}}\int_{0}^{\infty}e^{-t^{2}}dt=1. \] \subsubsection{Double sums or products} \label{subsec:settinsDouble-sums-prods}Sums or products can be iterated. For instance, the exponential function can be calculated this way: \begin{verbatim} \eval[p] {\[ \sum_{k=0}^{\infty} \prod_{m=1}^{k}\frac{x}{m} \]}[x=2] \end{verbatim} $\Longrightarrow$ \eval[p] {\[ \sum_{k=0}^{\infty} \prod_{m=1}^{k}\frac{x}{m} \]}[x=2] \noindent which is \verb`\eval{$ e^2 $}` $\Longrightarrow\eval{\ensuremath{e^{2}}}$. A second example is afforded by Euler's transformation of series (\emph{HMF~}3.6.27). To calculate $e^{-1}$ we use \begin{verbatim} \eval[p] {\[ \sum_{n=0}^{\infty} \frac{(-1)^{n}}{n!} \]}[3]\info{sum}. \end{verbatim} $\Longrightarrow$ \eval[p]{\[ \sum_{n=0}^{\infty}\frac{(-1)^{n}}{n!} \]}[3]\info{sum}. Following Euler, this series can be transformed to the form \begin{verbatim} \eval[p,S?=1]{\[ \sum_{k=0}^\infty \frac{(-1)^k}{2^{k+1}} \sum_{n=0}^k(-1)^n\binom kn \frac1{(k-n)!} \]}[3]\nmcInfo{sum}. \end{verbatim} $\Longrightarrow$ \eval[p,S?=1]{\[ \sum_{k=0}^\infty \frac{(-1)^k}{2^{k+1}}\sum_{n=0}^k(-1)^n\binom kn \frac1{(k-n)!} \]}[3]\nmcInfo{sum}. Note the setting \verb`S?=1`. Without it, the summation stops after $1$ term, the $k=0$ term, because the $k=1$ term vanishes. With \verb`S?=1` it takes $16$ terms of the \emph{outer }sum to reach the stopping criterion. Since that sum starts at $0$, that means that changing the upper limit from $\infty$ to $15$ should give the same result – which it does, taking $\tfrac{1}{2}\times16\times17=136$ terms in total to get there, to be compared with the $9$ terms of the earlier simpler sum, and the terms are more complicated. Obviously such double sums are computationally intensive. \section{Formatting commands} \label{sec:calcFormatting-commands}There are many formatting commands which change the layout of a formula on the page but do not alter its calculational content. \texttt{numerica} copes with a great many of these, although there will surely be some that have been overlooked\footnote{Please contact the author in that case: ajparsloe@gmail.com} and which will trigger an `Unknown token' message; see §\ref{chap:errorsErrors}. \subsection{Spaces, phantoms, struts} These include cryptic forms like \verb`\,` \verb`\:` and \verb`\>`, \verb`\;` and the corresponding `verbose' forms, \verb`\thinspace`, \verb`\medspace` and \verb`\thickspace` and their negative equivalents \verb`\!` or \verb`\negthinspace`, \verb`\negmedspace` and \verb`\negthickspace`: \begin{centred} \verb`\eval{$ 1\negthickspace+\negthickspace 1 $}` $\Longrightarrow$ \eval{$ 1\negthickspace+\negthickspace 1 $} \end{centred} which is a tiny bit tighter than the text spacing, 1+1, and much tighter than the usual math spacing $1+1$ – but it doesn't affect the result of the calculation. Other spacing commands are \verb`\quad` and \verb`\qquad`, and \verb`\hspace{arg}` and \verb`\mspace{arg}`. For \verb`\hspace` there is also a starred form, \verb`\hspace*{arg}`. Phantoms similarly take an argument: \verb`\phantom{arg}`, \verb`\hphantom{arg}` and \verb`\vphantom{arg}`. \begin{centred} \verb`\eval{$ 1\hphantom{mmm}+\hphantom{mmm}1 $}` $\Longrightarrow$ \eval{$ 1\hphantom{mmm}+ \hphantom{mmm}1 $}. \end{centred} Like \verb`\vphantom`, struts allow vertical spacing adjustments. \texttt{numerica} should digest both \verb`\xmathstrut[optarg]{arg}` from \texttt{mathtools} and its `baby cousin' \verb`\mathstrut` from \TeX . An example from \emph{The \TeX{} book} demonstrating the use of \verb`\mathstrut` is \begin{verbatim} \eval{$\sqrt{\mathstrut a}+\sqrt{\mathstrut d}+ \sqrt{\mathstrut y}$}[a=4,d=9,y=16] \end{verbatim} $\Longrightarrow$ \eval{$\sqrt{\mathstrut a}+\sqrt{\mathstrut d}+ \sqrt{\mathstrut y}$}[a=4,d=9,y=16] . \medskip{} And here is an evaluation of a somewhat ridiculous expression modified from the \texttt{mathtools} documentation that uses \verb`\xmathstrut`: \begin{verbatim} \eval{\[ \frac{ \frac{\xmathstrut{0.1} 2\ceil x-1} { \xmathstrut{0.25} \ceil x-\sin x } } {\xmathstrut{0.4} \sqrt{10-\ceil x} } \]} [x=\pi/6] \end{verbatim} $\Longrightarrow$ \eval{\[ \frac{ \frac{\xmathstrut{0.1} 2\ceil x-1} { \xmathstrut{0.25} \ceil x-\sin x } } {\xmathstrut{0.4} \sqrt{10-\ceil x} } \]} [x=\pi/6] \subsubsection{\texttt{\textbackslash mkern}, \texttt{\textbackslash mskip}} From version 3.0.0, both \verb`\mkern` and \verb`\mskip` are recognized by \texttt{numerica}. \verb`\mkern` should be followed either by an explicit space specification in \verb`mu` (math units), like \verb`3 mu` (or \verb`3mu`), or a control sequence containing such a specification; \verb`\mkern` should be followed by an explicit `glue' specification or a control sequence containing such a specification. A glue spec. is a distance in \verb`mu` possibly followed by some stretch and shrink, e.g.\ \verb`3 mu plus 1 mu minus 2 mu` (or \verb`3muplus1muminus2mu`) with or without the \verb`plus` and \verb`minus` parts. A silly example of the use of \verb`\mkern` and \verb`\mskip` is the following: \begin{verbatim} \def\negvmu{-5mu} \eval[env=$]{ 1 \mkern \negvmu + \mskip 18mu plus 6mu minus 9mu 1 } \end{verbatim} $\Longrightarrow$ \def\negvmu{-5mu} \eval[env=$]{ 1 \mkern \negvmu + \mskip 18mu plus 6mu minus 9mu 1 }. \subsection{\texttt{\textbackslash splitfrac}, \texttt{\textbackslash splitdfrac}} The \texttt{mathtools} package provides \verb`\splitfrac` and \verb`\splitdfrac` to aid handling of clumsy fractions. I've mangled the example in the \texttt{mathtools} documentation illustrating this command to produce an even more ridiculous illustration, adding to the mess an enormous square root, \verb`\left` and \verb`\right` modifiers, and command-form parentheses; also the use of \verb`\dfrac`. In the other direction, the \verb`vv=` in the settings option suppresses the vv-list (see §\ref{subsec:settingsVvDisplayChangeLocal}). A little mental arithmetic will convince that we are evaluating the square root of $(9\times7)^{2}$ which indeed is what we get: \begin{verbatim} \eval[p=.,vv=] {\[ \sqrt{ \left\lparen \frac{ \splitfrac{xy + xy + xy + xy + xy} {+ xy + xy + xy + xy} } { \dfrac z7} \right\rparen \left\lparen \frac{ \splitdfrac{xy + xy + xy + xy + xy} {+ xy + xy + xy + xy} } {\dfrac z7}\right\rparen} \]}[x=2,y=5,z=10] \end{verbatim} $\Longrightarrow$ \eval[p=.,vv=]{\[ \sqrt{\left\lparen \frac{ \splitfrac{xy + xy + xy + xy + xy} {+ xy + xy + xy + xy} } { \dfrac z7} \right\rparen \left\lparen \frac{ \splitdfrac{xy + xy + xy + xy + xy} {+ xy + xy + xy + xy} } {\dfrac z7}\right\rparen} \]}[x=2,y=5,z=10] \subsection{Colour} \label{subsec:calcColour}(Anglicised spelling at least for the heading!) If you add to the preamble of your document the line \begin{verbatim} \usepackage{color} \end{verbatim} two commands become available, \verb`\textcolor[optarg]{arg1}{arg2}` and the declaration form of command, \verb`\color[optarg]{arg}`. \texttt{numerica} readily accepts the former in a formula to be evaluated: \begin{centred} \verb`\eval{$ \sin \tfrac\pi6n\textcolor{red}{T}+1 $}[T=9,n=3]` $\Longrightarrow$ \eval{$ \sin \tfrac\pi6n\textcolor{red}{T}+1 $}[T=9,n=3] \end{centred} (assuming you had some wish to highlight the time $T$). You can even colour the $T$ in the vv-list too, but it adds a lot of typing for a small gain: \begin{centred} \verb`\eval{$ \sin \tfrac\pi6n\textcolor{red}{T}+1 $}[\textcolor{red}{T}=9,n=3]` $\Longrightarrow$ \eval{$ \sin \tfrac\pi6n\textcolor{red}{T}+1 $}[\textcolor{red}{T}=9,n=3]. \end{centred} However \verb`\color` is a \emph{declaration} form of command. It has effect until the end of the current group or environment. If you want to restrict it to only part of that group you need to em-brace the command and what it is to apply to, \begin{verbatim} {\color{red}} in ` \end{centred} where \verb`` will usually be \verb`formula` or \verb`variable=value list` or possibly some more specific location like \verb`sum` or \verb`product`. \verb`` is the line number in the \verb`.tex` file where the error occurs. These messages in the log do not halt compilation. They allow the user to pinpoint – especially helpful in a long document – the actual line in the \verb`.tex` file where the \texttt{numerica} error occurs. Before discussing specific error messages, note that there is a debug facility (of a sort) discussed below in §\ref{sec:settingsDebug}. \section{Specific messages} \texttt{numerica} error messages that appear in the \texttt{pdf} in place of the expected result are in two parts: a \emph{what} part and a \emph{where} part. \subsection{Mismatched brackets} \label{subsec:errorsMismatched-brackets}An unmatched left parenthesis or other left bracket (in this case a missing right parenthesis) usually results in a \texttt{numerica} error: \begin{centred} \verb`$\eval{\sin(\pi/(1+x)}[x=1]$` $\Longrightarrow$ $\eval{\sin(\pi/(1+x)}[x=1]$ \end{centred} For the same error in the vv-list, the \emph{what}-part remains unchanged but the \emph{where}-part is altered: \begin{centred} \verb`$\eval{ 1+y }[x=1,y=\sin(\pi/(1+x)]$` $\Longrightarrow$ $\eval{ 1+y }[y=\sin(\pi/(1+x),x=1]$ \end{centred} An unmatched right parenthesis or other right bracket (in this case a missing \emph{left} parenthesis) usually results in a similar \texttt{numerica} error: \begin{centred} \verb`$\eval{2((x+y)/(y+z)))^2}[x=1,y=2,z=3]$` $\Longrightarrow$ $\eval{2((x+y)/(y+z)))^{2}}[x=1,y=2,z=3]$ \end{centred} But note that an unmatched modifier like \verb`\left` or \verb`\right` is a \LaTeX{} error and is caught by \LaTeX{} before \texttt{numerica} can respond and so results in a terminal and logfile message. \subsection{Unknown tokens} An `Unknown token' message can arise in a number of ways. If an expression involves a number of variables, some of which depend on others, their order in the vv-list matters: \begin{center} \verb`$\eval{\tfrac12 vt}[t=2,v=gt,g=9.8]$` $\Longrightarrow$ \eval{\tfrac{1}{2}vt}[t=2,v=gt,g=9.8] \par\end{center} \noindent The vv-list is evaluated from the \emph{right} so that in this example the variable \verb`v` depends on a quantity \verb`t` that is not yet defined. Hence the message. The remedy is to move \verb`t` to the right of \verb`v` in the vv-list. Similarly, if we use a variable in the formula that has not been assigned a value in the vv-list, we again get the `Unknown token' message, but this time the location is the formula: \begin{centred} \verb`$\eval{\pi r^2h}[r=3]$` $\Longrightarrow$ \eval{\pi r^{2}h}[r=3] \end{centred} The remedy obviously is to assign a value to \verb`h` in the vv-list\texttt{.} The same message will result if a mathematical operation or function is used that has not been implemented in \texttt{numerica}: \begin{centred} \verb`$\eval{u \bmod v }[v=7,u=3]$` $\Longrightarrow$ \eval{u\bmod v}[v=7,u=3] \end{centred} A missing comma in the vv-list will generally result in an unknown token message: \begin{centred} \verb`$\eval{axy}[a=3 y=2,x=1]$` $\Longrightarrow$ \eval{axy}[a=3y=2,x=1] \end{centred} Because of the missing comma, \texttt{numerica} sees only two variables in the vv-list, \verb`x` and \verb`a` and assumes \verb`a` has the `value' \verb`3y=2`, an expression which it then tries to evaluate, but \verb`y` has not been assigned a value. Parenthetically, if you give \verb`y` a value, say \verb`y=2/3`, the expression evaluates, treating the combination \verb`3 y=2` as a comparison evaluating to true for this value of \verb`y`, meaning \verb`a=1` and \begin{centred} \verb`$\eval{axy}[a=3 y=2,y=2/3,x=1]$` $\Longrightarrow$ $\vsp\eval{axy}[a=3 y=2,y=2/3,x=1]$. \end{centred} \emph{Extra} commas in the vv-list should cause no problems: \begin{centred} \verb`$\eval{axy}[,a=3,,y=2,x=1,]$` $\Longrightarrow$ $\eval{axy}[,a=3,,y=2,x=1,]$ . \end{centred} The presence of multi-token variables can also cause an unknown token message if the check for such variables is turned off; see §\ref{subsec:settingsMultitokSwitch}. \subsection{Overlooked value assignments} Perhaps if one is evaluating a long formula with a number of variables and assigning different experimental values to them to see the effect, a variable might be overlooked (I have done this). The example is too simple to be a likely candidate for this error but shows the message: \begin{centred} \verb`$\eval{axy}[a=3,y=,x=1]$` $\Longrightarrow$ \eval{axy}[a=3,y=,x=1] \end{centred} In the example the variable \verb`y` has been overlooked. The remedy is obvious. \subsection{Negative integers in the wrong place} Factorials (apart from the double factorial \eval{$(-1)!!$}), binomial coefficients, and $n$-th roots, require positive or at least non-negative integers. \begin{centred} \verb`\eval{$ \sqrt[-1]{2} $}` $\Longrightarrow$ \eval{$ \sqrt[-1]{2} $}\medskip{} \verb`\eval{$ (-3)! $}` $\Longrightarrow$ \eval{$ (-3)! $}\medskip{} \verb`\eval{$ \binom{7}{-3} $}` $\Longrightarrow$ \eval{$ \binom{7}{-3} $} \end{centred} \subsection{Invalid base for \texttt{\textbackslash log}} ISO recommends using \verb`\log` only with a subscripted base specified, a recommendation honoured in the breach rather than the observance. \texttt{numerica} assumes that when \verb`\log` is used unsubscripted, the base is 10 and that \verb`\ln` is used for base \verb`e`. Suppose you want to make $12$ the base, but forget to put braces around the $12$: \begin{centred} \verb`$\eval{ \log_12 1728 }$` $\Longrightarrow$ $\eval{ \log_12 1728 } $ \end{centred} Here, \texttt{numerica} has taken \texttt{1} as the base (and $2$ as the argument) of the logarithm and responds accordingly. \subsection{Environment errors} Errors can arise from environments wrongly used, although environmental precedence (§\ref{sec:calcEnvironment-precedence}) sidesteps a number of apparent problems. Some environments – \verb`aligned`, \verb`alignedat`, \verb`gathered`, \verb`cases`, \verb`dcases` and \verb`array` – can be used only within another math environment. Thus \begin{centred} \verb`\eval[env=aligned,ff]{ \sin x, \cos x, \tan x }[x=\pi/6]` $\Longrightarrow$ \eval[env=aligned,ff]{\sin x, \cos x, \tan x}[x=\pi/6] \end{centred} The remedy, obviously, is to put the \verb`\eval` command between, say, \verb`\[`, \verb`\]` delimiters. In the other direction, because of environment precedence, forgetting the \verb`ed` at the end of the \verb`env`-ironment does not result in an error but displays the result in the outer, wrapping environment: \begin{verbatim} \[ \eval[env=align,p=.,ff] { \sin x, \cos x, \tan x}[x=\pi/6] \] \end{verbatim} $\Longrightarrow$ \[ \eval[env=align,p=.,ff] { \sin x, \cos x, \tan x}[x=\pi/6] \] An unknown environment produces a message: \begin{verbatim} \eval[env=foo]{ \pi }\par \eval{\begin{foo} \pi \end{foo}} \end{verbatim} $\Longrightarrow$ \eval[env=foo]{ \pi }\par \eval{\begin{foo} \pi \end{foo}} \subsection{\texttt{l3fp} errors} Some errors arising at the \texttt{l3fp} level are trapped and a message displayed. \subsubsection{Dividing by zero} \begin{centred} \verb`$\eval{1/\sin x}[x=0]$` $\Longrightarrow$ \eval{1/\sin x}[x=0] \end{centred} Note however that \begin{centred} \verb`$\eval{1/\sin x}[x=\pi]$` $\Longrightarrow\,\eval{1/\sin x}[x=\pi]$, \end{centred} because of rounding errors in distant decimal places. No doubt this is true for other functions as well. \subsubsection{Invalid operation} \label{subsec:errorsInverse-powers}Finding inverse integer powers of \emph{positive} numbers should always be possible, but raising a \emph{negative} number to an inverse power generates an error even when – mathematically – it should not: \begin{centred} \verb`\eval{$ (-125)^{1/3} $}` $\Longrightarrow$ \eval{$ (-125)^{1/3} $} \end{centred} This is a feature of floating point arithmetic. When a number is raised to a rational power, say $p/q$ where $p$ and $q$ are non-zero integers, then the result is the $p$th power of the $q$-th root of the number. Can a $q$-th root be taken? If our floating point system used (for ease of illustration) only $4$ significant digits, $p/q=1/3$ would be the fraction $3333/10^{4}$, an odd numerator over an even denominator. But a negative number does not possess an even ($10^{4}$th) root. The user needs to take care of the minus sign, in this case simply by omitting the parentheses. Trying to evaluate a function like a factorial or square root or inverse trig. function outside its domain of definition also produces this error: \begin{centred} \verb`$\eval{\arccos x}[x=2]$` $\Longrightarrow$ $\eval{\arccos x}[x=2]$ \end{centred} In this case the inverse cosine, which is defined only on the interval $[-1,1]$, has been fed the value $2$. Trying to evaluate an expression that resolves to $0/0$ also produces this message: \begin{centred} \verb`$\eval{\frac{1-y}{x-2}}[x=2,y=1]$` $\Longrightarrow$ \eval{\frac{1-y}{x-2}}[x=2,y=1] \end{centred} \subsubsection{Overflow/underflow} The factorial (discussed in §\ref{sec:calcFactorialsBinom}) provides an example of overflow: \begin{centred} \verb`$\eval{3249!}$`\texttt{ }$\Longrightarrow$ \eval{3249! } \end{centred} This is hardly surprising since \begin{centred} \verb`$\eval{3248!}[x]$` $\Longrightarrow$ $\eval{3248!}[x]$. \end{centred} There is a limit on the size of exponents that \texttt{l3fp} can handle. A number in the form $a\times10^{b}$ must have $-10001\le b<10000$. If this is not the case an overflow or underflow condition occurs. As the examples show, an overflow condition generates a \texttt{numerica} error. For underflow, where the number is closer to $0$ than $10^{-10001}$, \texttt{l3fp} assigns a zero value to the quantity. \texttt{numerica} accepts the zero value and the error is ignored. \subsection{Obsolete settings} (For settings, see the next chapter.) Some settings in earlier versions of \texttt{numerica} may be superseded by later developments and rendered obsolete. With version 3.0.0 there are two of these obsolete settings, and some deprecations. The superseded settings are these: \begin{itemize} \item \verb`()` \quad{}previously a setting for handling complicated arguments to trigonometric functions. Now \LaTeX{} braces are recommended; see §\ref{subsec:evalBraced-groups} and §\ref{subsec:calcComplicated-arguments}. \item \verb`reuse` \quad{}previously a setting determining what is saved with the \verb`\nmcReuse` command (§\ref{sec:supplReuse}). Now only the numerical result is saved – although it can be saved in a variety of forms, depending on the result-format specification in the \verb`\eval` command. \end{itemize} Use of either setting generates a similar message, changing only the content between the quote marks in the following: \begin{centred} \verb`\eval[()=2]{$ \sin\frac12\bigl(A+B\bigr) $}[A=\pi/5,B=\pi/7]` $\Longrightarrow$ \eval[()=2] {$ \sin\frac12\bigl(A+B\bigr) $}[A=\pi/5,B=\pi/7] \end{centred} \chapter{Settings} \label{chap:settingsSettings}The first square-bracketed optional argument (and second argument overall) of the \verb`\nmcEvaluate` command (see Chapter~\ref{chap:evalEvaluate}) is the settings option preceding the main argument that contain the expression or expressions to be evaluated. The settings option is a comma-separated\footnote{Including when the \texttt{comma} package option is used. No \emph{decimal} number is required in the settings, only integers.} \emph{key=value} list. Such\emph{ }lists tend to be wordy. For back-of-envelope calculations one wants to be able to `dash off' the calculation; hence short, cryptically named keys have been used. Many settings are generic, applicable not only to \verb`\nmcEvaluate` but also to other commands that are available in \texttt{numerica} (see Chapter~\ref{chap:Supplementary-commands}) and the packages \texttt{numerica-plus} and \texttt{numerica-tables} – briefly described in §\ref{subsec:introPackagesOptions}. A calculation is effected against a background of assigned values for various quantities – the calculational environment. For a particular calculation, these values may not be appropriate; or you may have different preferences. The complete list of such settings available for \verb`\nmcEvaluate` (or \verb`\eval`) is shown in Tables~\ref{tab:settingsFunctionalSettingsParams} and \ref{tab:settingsDisplaySettingsParams}, separated into \emph{functional} settings (which affect the calculation) and \emph{display} settings (which don't). \begin{itemize} \item The \emph{initial} values listed are the values assigned to the settings initially at each use of the \verb`\eval` (and other) commands. \item A \emph{default} value is the value assigned to the setting if you simply enter its name (without assigning a value to it) in the settings option. \item $0/1$ alternatives are interpreted as $1$ meaning ON and $0$ meaning OFF. \end{itemize} For example, entering \verb`o` in the settings option is equivalent to entering \verb`o=1`, meaning angles are assumed to be in degrees, but unless \verb`o` is entered, \verb`\eval` uses \verb`o=0`, the initial value, meaning angles are assumed to be in radians. \begin{table} \centering \centering{}\caption{Functional settings parameters}\label{tab:settingsFunctionalSettingsParams} \begin{center} \begin{tabular}{>{\raggedright}p{1.5cm}>{\raggedright}p{1.5cm}>{\raggedright}p{3cm}>{\raggedright}p{1.5cm}>{\raggedright}p{1.5cm}} \toprule {\small key} & {\small type} & {\small meaning} & {\small default} & {\small initial}\tabularnewline \midrule {\small\texttt{dbg}} & {\small int} & {\small debug data} & & {\small\texttt{0}}\tabularnewline {\small\texttt{view}} & & {\small\texttt{dbg=1}} & {\small\texttt{dbg=1}} & \tabularnewline {\small\texttt{\textasciicircum}} & {\small char} & {\small exp. mark for sci. notation input} & {\small\texttt{e}} & \tabularnewline {\small\texttt{xx}} & {\small int (0/1)} & {\small accept multi-token variables} & & {\small\texttt{1}}\tabularnewline \multirow{2}{1.5cm}{\texttt{ff}} & \multirow{2}{1.5cm}{{\small char}} & \multirow{2}{3cm}{{\small main arg. multi- formula delimiter}} & \multicolumn{2}{l}{{\small\texttt{, }}{\small (if decimal dot)}}\tabularnewline & & & \multicolumn{2}{l}{{\small\texttt{; }}{\small (if decimal comma)}}\tabularnewline {\small\texttt{1s2}} & {\small int (0/1)} & {\small allow spaced digit groups in numbers} & {\small\texttt{1}} & {\small\texttt{0}}\tabularnewline {\small\texttt{/min}} & {\small$\text{int}\ge1$} & {\small fraction form denom- inator search start} & & {\small\texttt{1}}\tabularnewline {\small\texttt{/max}} & {\small$\text{int}\ge1$} & {\small fraction form denom- inator search end} & & {\small\texttt{200}}\tabularnewline {\small\texttt{vv@}} & \multirow{3}{1.5cm}{{\small int (0/1)}} & \multirow{3}{3cm}{{\small vv-list calculation mode}} & \multirow{3}{1.5cm}{} & \multirow{3}{1.5cm}{{\small\texttt{0}}}\tabularnewline \multirow{2}{1.5cm}{{\small\texttt{vvmode}}} & & & & \tabularnewline & & & & \tabularnewline {\small\texttt{o}} & {\small int (0/1)} & {\small trig. function args in degrees} & {\small\texttt{1}} & {\small\texttt{0}}\tabularnewline {\small\texttt{log}} & {\small num} & {\small base of logs for }{\small{\small\verb`\log`}} & & {\small\texttt{10}}\tabularnewline {\small\texttt{S+}} & {\small int} & {\small extra rounding, sums} & & {\small\texttt{2}}\tabularnewline {\small\texttt{S?}} & {\small$\text{int}\ge0$} & {\small number of query terms, sums} & & {\small\texttt{0}}\tabularnewline {\small\texttt{P+}} & {\small int} & {\small extra rounding, products } & & {\small\texttt{2}}\tabularnewline {\small\texttt{P?}} & {\small$\text{int}\ge0$} & {\small number of query terms, products} & & {\small\texttt{0}}\tabularnewline \cmidrule{1-1} {\small\texttt{()}} & \multicolumn{4}{l}{{\small obsolete; see §\ref{sec:settinsDeprecatedObsoleteOptions}}}\tabularnewline {\small\texttt{reuse}} & \multicolumn{4}{l}{{\small obsolete; see §\ref{sec:settinsDeprecatedObsoleteOptions}}}\tabularnewline {\small\texttt{{*}}} & \multicolumn{4}{l}{{\small obsolete; see §\ref{sec:settinsDeprecatedObsoleteOptions}}}\tabularnewline \bottomrule \end{tabular} \par\end{center} \end{table} \begin{table} \centering \caption{Display settings parameters}\label{tab:settingsDisplaySettingsParams} \medskip{} \begin{tabular}{>{\raggedright}p{1cm}>{\raggedright}p{1.5cm}>{\raggedright}p{3.5cm}>{\centering}p{1.5cm}>{\centering}p{1.5cm}} \toprule {\small key} & {\small type} & {\small meaning} & {\small default} & {\small initial}\tabularnewline \texttt{f} & {\small int (0/1)} & {\small show/hide formula} & & \tabularnewline {\small\texttt{p}} & {\small token(s)} & {\small concluding punctuation } & {\small\texttt{,}} & \tabularnewline {\small\texttt{pp}} & {\small token(s)} & {\small multi-formula inter- result punctuation} & {\small\texttt{,}} & \tabularnewline \cmidrule{1-1} {\small\texttt{env}} & {\small token(s)} & {\small math environment} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{arg}} & {\small token(s)} & {\small arg. for }{\small\texttt{-at}}{\small , }{\small\texttt{array}}{\small{} envs} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{eq}} & {\small token(s)} & {\small relation symbol} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{vv}} & {\small token(s)} & {\small vv-list specification} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{sep}} & {\small token(s)} & {\small separator between multi-formula results} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{\textbackslash\}}} & {\small token(s)} & {\small right bracket for inner math environments} & {\small\textbackslash{} }{\small\texttt{\textbackslash\}}} & \tabularnewline \cmidrule{1-1} {\small\texttt{vvi}} & \multicolumn{4}{l}{{\small deprecated; use }{\small\texttt{vv }}}\tabularnewline {\small\texttt{vvd}} & \multicolumn{4}{l}{{\small deprecated; use }{\small\texttt{vv}}}\tabularnewline \bottomrule \end{tabular} \end{table} \section{\textquoteleft Debug\textquoteright{} facility} \label{sec:settingsDebug}It is rather grandiose to call this a debug facility, but if a calculation goes wrong or produces a surprising result, \texttt{numerica} offers a means of examining various quantities at some intermediate stages on the way to the final result. To use the facility, enter \begin{verbatim} dbg = \end{verbatim} into the settings option. (White space around the equals sign is optional.) \begin{itemize} \item \verb`dbg=0`\texttt{ }turns off the debug function, displays the result or error message (this is the initial setting); \item \verb`dbg=1`\texttt{ }equivalent to \verb`dbg=2*3*5*7*11` for \verb`\eval`; \end{itemize} The `magic' integers are the first few prime numbers and their products \begin{itemize} \item \verb`dbg=2` displays the formula after multi-token variables have been converted to their single token form, \verb`\nmc_a`, \verb`\nmc_b`, etc.; \item \verb`dbg=3` displays the vv-list after multi-token variables have been converted to their single token form; \item \verb`dbg=5` displays the stored variables and their values \emph{after} evaluation (\verb`dbg=3` lists the values as expressions); \item \verb`dbg=7` displays the formula after it has been fp-ified but before it has been fed to \texttt{l3fp} to evaluate; \begin{itemize} \item When interpreting the fp-form, be aware that differences in the ways \texttt{numerica} and \texttt{l3fp} read formulas can lead to more or fewer parentheses than seem strictly necessary. In particular be aware that in \texttt{l3fp} function calls bind most tightly so that, for example, \verb`sin 2pi` evaluates not to zero but to $(\sin2)\times\pi$, and \verb`sin x^2` evaluates to $(\sin x)^{2}$. \texttt{numerica} takes care of the former by inserting extra parentheses and exploits the latter by not inserting parentheses. \end{itemize} \item \verb`dbg=11` displays the \LaTeX{} form of the final display; it will contain, \emph{inter alia}, the numerical result. \end{itemize} To display two or more of the debug elements simultaneously, use the product of their debug numbers for the magic integer. This can be entered either as the multiplied-out product, or as the `waiting to be evaluated' product with asterisks (stars) between the factors. Thus \verb`dbg=6` and \verb`dbg=2*3` each display both the vv-list and formula after multi-token variables have been converted to single token form; \verb`dbg=77` or \verb`dbg=7*11` each display both the form of the expression that is fed to \texttt{l3fp} (the `fp-ified' form) and the \LaTeX{} form of the final display (including the numerical result). And generally, if an integer is divisible by $2$, $3$, $5$, $7$, or $11$ the corresponding element of the debug display will be shown. Both \verb`dbg=2310` and \verb`dbg=2*3*5*7*11` display all five elements, but rather than remembering this product or typing all those digits and asterisks, it suffices to enter \verb`dbg=1`. This is equivalent and displays all elements. The debug option uses an \verb`aligned`\texttt{ }or \verb`align*` environment to display its wares, depending on whether \verb`\eval` lies within or around a math environment. The following uses \verb`align*` and shows how multi-token variables are handled and how a chain of comparisons is evaluated (§\ref{subsec:evalBoolean-output}): \begin{verbatim} \eval[dbg=1]{ a < 2a' < 3a'' } [a=\pi,a'=\phi,a''=e\gamma][4???] \end{verbatim} $\Longrightarrow$ \eval[dbg=1]{ a < 2a' < 3a'' } [a=\pi,a'=\phi,a''=e\gamma][4???] \noindent The various items are displayed in chronological order. First comes the formula after conversion of multi-token to single-token variables, then the vv-list in those single-token variables; these are created essentially at the same time. Next the stored values of the variables are displayed. These are the values \emph{after }vv-list evaluation. (Even if the \verb`comma` package option is being used and the decimal point is a comma, the stored values will display with a decimal dot because this is what \texttt{l3fp} uses.) The fourth element both in the display and chronologically is the fp-ified formula. Often this can be a thicket of parentheses, especially if unary functions or fractions are involved. The final element of both the display and chronologically is the \LaTeX{} form of the display. In the example it is skimpy, because no environment was specified. Putting, say, \verb`env=$` in the settings option results in a much fuller final line: \begin{verbatim} \eval[dbg=11,env=$]{ a < 2a' < 3a'' } [a=\pi,a'=\phi,a''=e\gamma][4???] \end{verbatim} $\Longrightarrow$ \eval[dbg=11,env=$]{ a < 2a' < 3a'' } [a=\pi,a'=\phi,a''=e\gamma][4???]By using \verb`dbg=11` in the settings option I have limited the display to the \LaTeX{} form, since the other elements are unchanged. Mathematical operations that have no direct counterpart in \texttt{l3fp} contribute only their numerical value to the fp-form. This applies to sums and products, double factorials, partly to binomial coefficients, and also to \verb`\eval` and other commands when nested one within another (see Chapter~\ref{sec:miscNesting}). The following (ridiculous) example illustrates the matter: \begin{verbatim} \eval[dbg=1]{\[ \sum_{n=1}^k n + \binom{2k}{m} - \frac1{4k} + \prod_{n=2}^k (1-1/n) + m!! \]}[m=6,k=5] \end{verbatim} $\Longrightarrow$ \eval[dbg=1]{\[ \sum_{n=1}^k n + \binom{2k}{m} - \frac1{4k} + \prod_{n=2}^k (1-1/n) + m!! \]}[m=6,k=5]($0$\textdegree{}~C in kelvin!) In the \verb`fp-form` line, the various contributions to the overall result are displayed simply as numbers because \texttt{l3fp} does not (at least as yet) handle these elements natively. \subsection{Multi-formula calculations} Using \verb`dbg=1` on a multi-formula calculation displays the formula and fp-form of the last formula `digested' by \verb`\eval`. Other elements of the debug display are not limited in this way. If all formulas are successfully evaluated then this will be the final formula entered in the multi-formula calculation. But should there be an error when evaluating one of the component formulas, \emph{that} will be the last formula evaluated; the debug information will pertain to that formula. For example, \begin{verbatim} \eval[dbg=1,ff]{$ \sin x, \arccos x, \tan x $}[x=\pi/3] \end{verbatim} $\Longrightarrow$ \eval[dbg=1,ff]{$ \sin x, \arccos x, \tan x $}[x=\pi/3]Both error message and debug information are present, the debug information pertaining to the formula, \verb`\arccos x`, where the error occurred. \subsection{Negative \texttt{dbg} values} Had the \verb`$` delimiters been placed around rather than within the \verb`\eval` command in the last example, both error message and debug display would have been crowded onto the one line and would generally exceed the dimensions of the paper. The remedy is to turn off the error message by using a \emph{negative} debug number of the same numerical value, in this case \verb`dbg=-1` (note that this use of \emph{negative} debug numbers differs from their use in previous versions of \texttt{numerica}): \begin{verbatim} $\eval[dbg=-1,ff]{ \sin x, \arccos x, \tan x }[x=\pi/3]$ \end{verbatim} $\Longrightarrow$ $\eval[dbg=-1,ff]{ \sin x, \arccos x, \tan x}[x=\pi/3]$ \subsection{\texttt{view} setting} Putting \verb`dbg=1` in the settings option may seem somewhat obscure in order to view internal values of \texttt{numerica}. Writing \verb`view` instead (it does not need to be equated to anything) is equivalent and should be easier to remember. \section{Other functional settings} \subsection{Inputting numbers in scientific notation} \label{subsec:settingsInputtingSciNotation}Outputting numbers in scientific notation is controlled by the final trailing argument of the \verb`\eval` command. Such output is turned off by default and needs to be explicitly ordered. Similarly, \emph{inputting} numbers in scientific notation is turned off by default and needs to be explicitly ordered. To turn it on, write \begin{verbatim} ^ = \end{verbatim} \noindent in the settings option, where \verb`` is any single character, usually \verb`e` or \verb`d` or their upper-casings, but not restricted to them: \verb`^=@` for instance is perfectly possible, and has the advantage over \verb`e` or \verb`d` that it doesn't conflict with the use of the character as a variable or constant. \begin{centred} \verb`$ \eval[^=@]{ 0.123 + 1.23@-1 } $` $\Longrightarrow$ $ \eval[^=@]{ 0.123 + 1.23@-1 } $. \end{centred} The example shows that numbers can still be input in ordinary decimal form at the same time as scientific notation is used. The default exponent mark is \verb`e` so that entering \verb`^` in the settings option is equivalent to entering \verb`^=e` and will suffice to turn on the inputting of numbers in scientific notation using this mark: \begin{centred} \verb`$ \eval[^]{ 0.123 + 1.23e-1 } $` $\Longrightarrow$ $ \eval[^]{ 0.123 + 1.23e-1 } $. \end{centred} With letters for the exponent mark – say \verb`d` or \verb`e` – there is a problem in interpreting forms like \verb`8d-3` or \verb`2e-1`. Does such a form denote a number in scientific notation or an algebraic expression? In \texttt{numerica}, if the settings option shows \verb`^=d`, then a form like \verb`8d-3` is treated as a number in scientific notation. Similarly for \verb`e` or any other letter used as the exponent mark for the input of scientific numbers. (But only one character can be so used at a time.) Note that the number \emph{must start with a digit}: \verb`e-1` for instance does not and will be treated as an algebraic expression involving the exponential constant: \begin{centred} \verb`$ \eval[^]{ x+e-1 }[x=1] $` $\Longrightarrow$ $ \eval[^]{ x+e-1 }[x=1] $ \end{centred} but \begin{centred} \verb`$ \eval[^]{ x+1e-1 }[x=1] $` $\Longrightarrow$ $ \eval[^]{ x+1e-1 }[x=1] $. \end{centred} A problem of appearance arises if scientific numbers appear in the vv-list or formula and either is displayed in the result. A number like \verb`2e-1` will display as $2e-1$, as if it were an algebraic expression. In version 1 of \texttt{numerica} the cure was to wrap \verb`2e-1` in a \verb`\text` or \verb`\mbox` command. In version 2 of \texttt{numerica} the behaviour of \verb`\text` and \verb`\mbox` was re-thought; see §\ref{subsec:calcText-mbox-fonts}. Their contents are invisible to the \verb`\eval` command. The solution is to wrap \verb`2e-1` in a \verb`\textrm` or \verb`\textsf` or \verb`\texttt` command. These commands were not recognized by \verb`\eval` in version 1 but in versions from 2.0.0: \begin{centred} \verb`\eval[^=e]{$ 5x $ }[x=\texttt{2e-1}]` $\Longrightarrow$ \eval[^=e]{$ 5x $ }[x=\texttt{2e-1}] , \verb`\eval[^=e]{$ 5\texttt{2e-1} $ }` $\Longrightarrow$ \eval[^=e]{$ 5(\texttt{2e-1}) $ } . \end{centred} If you use a particular character as the exponent marker for inputting numbers in scientific notation, it is good practice \emph{not} to use that character as a variable, not because it will cause an error but because it makes expressions harder to read. \subsection{Multi-token variables} \label{subsec:settingsMultitokSwitch}Variables need not consist of a single character or token (like $x$ or $\alpha$). Multi-token symbols like $x'$ or $t_{i}$ or $var$ are perfectly acceptable. For its internal operations, \texttt{numerica} converts such multi-token names to single tokens (as discussed in §\ref{subsec:evalVariableNames}). This conversion takes time. Even if there are no multi-token variables used at all, \texttt{numerica} still needs to check that that is so. There is a setting that allows a user to turn off or turn on the check for such variables by entering \begin{verbatim} xx = \end{verbatim} into the settings option. If \verb`` is \verb`0`, the check for (and conversion of) multi-token variables is turned off; if \verb`` is \verb`1` (or any other\emph{ non-zero} integer), the check, and conversion if needed, goes ahead. \texttt{numerica} assumes multi-token variables may be used (primed or subscripted variables are common) so \verb`xx=1` is assumed initially. (The name for the key, \verb`xx`, is chosen because \verb`x` is the most familiar variable of all, introduced in elementary algebra, and doubling it like this suggests multi-token-ness.) If checking is turned off when a multi-token variable is present, an error results. We don't need to turn on the check in the first of the following examples because that is the initial pre-set state. Explicitly turning it off in the second produces an error. \begin{centred} \verb`\eval{$ x_0^{\,2} $}[x_0=5]` $\Longrightarrow$ \eval{$ x_0^{\,2} $}[x_0=5],\medskip{} \verb`\eval[xx=0]{$ x_0^{\,2} $}[x_0=5]` $\Longrightarrow$\\ \eval[xx=0]{$ x_0^{\,2} $}[x_0=5] \end{centred} \subsection{Multi-formula separator} \label{subsec:settingsMulti-formula-separator}The \verb`\eval` command can evaluate more than one formula at a time. This is activated with the \verb`ff` setting. Entering \begin{verbatim} ff = \end{verbatim} in the settings option means multiple formulas separated by \verb`` in the main argument of \verb`\eval` will be evaluated. For example, using \verb`ff=|`: \begin{centred} \verb`\eval[ff=|,pp]{ \pi^e | e^\pi | 2\phi^{\phi\pi} }` $\Longrightarrow$ \eval[ff=|,pp]{ \pi^e | e^\pi | 2\phi^{\phi\pi} }. \end{centred} When \verb`ff` is used without the \verb`= ` part, it defaults to the vv-list separator – a comma if the decimal point is a dot (period, full stop), a semicolon if the decimal point is a comma (i.e.\ if the \verb`comma` package option is used). If \verb`ff=` is used, with nothing on the right of the equals sign, to prevent a \LaTeX{} error being raised, the vv-list separator is retained as the multi-formula separator. \subsection{Spaced digit grouping} \label{subsec:settingsDigitGroupingSpaces}Numbers containing many digits can be easier to read if the digits are grouped into blocks. \texttt{numerica} accepts \emph{as input} numbers with such grouped digits provided the intervening character is a space. This needs to be explicitly turned on with the setting \verb`1s2`: \begin{centred} \verb`\eval[1s2]{ 12 3456.7890 1234 }` $\Longrightarrow$ \eval[1s2=1]{ 12 3456.7890 1234 }. \end{centred} Without the \verb`1s2` setting, the separate blocks of digits are multiplied together: \begin{verbatim} \eval[dbg=77]{ 12 3456.7890 1234 } \end{verbatim} $\Longrightarrow$\eval[dbg=77]{$ 12 3456.7890 1234 $} \subsection{Fraction-form denominator limits} \label{subsec:settingsFractionOutput}To restrict the size of the denominator in fraction-form ouput \verb`\eval` has two settings \begin{verbatim} /min = /max = \end{verbatim} (Those are \emph{not} backslashes!) \verb`` is the value to start searching from for a denominator for the fraction; \verb`integer2` is the value to search to and then stop the search if none has been found (to the requested accuracy). The initial values are \verb`/min=1` and \verb`/max=200`. See the discussion at §\ref{subsec:evalFraction-form-output}. \subsection{Calculation mode} \label{subsec:settingsRecalcMode}A variable may change in the course of a calculation. This is certainly true of sums and products. If a parameter in the vv-list depends on the variable then that parameter will need to be recalculated, perhaps repeatedly, in the course of a calculation. By entering either \begin{verbatim} vv@ = \end{verbatim} or (as in version 1 of \texttt{numerica}), \begin{verbatim} vvmode = \end{verbatim} in the settings option it is possible to turn on or off the ability to repeatedly evaluate the vv-list; \verb`` here takes two possible values, \verb`0` or \verb`1`. \verb`vv@=0` (or \verb`vvmode=0`) means the vv-list is evaluated once at the start of the calculation; \verb`vv@=1` (or\texttt{ }\verb`vvmode=1`) means the vv-list is recalculated every time the relevant variable changes.\footnote{In version 1 of \texttt{numerica} only the \texttt{vvmode} name for this setting was available. To the author's eye, the \texttt{@} sign seems suggestively close to a symbol like $\circlearrowleft$ to mean `redo' (and is generally available on keyboards). } For example, in a sum it may be desirable to place the summand, or some part of it, in the vv-list. Since the summation variable obviously changes during the course of the calculation, we need to enter \verb`vv@=1` in the settings option. Repeating an earlier sum, \medskip{} \begin{verbatim} \eval[p=.,vv@=1]{\[ \sum_{k=1}^N f(k) \]} [N=100,f(k)=1/k^3,{k}=1][4] \end{verbatim} $\Longrightarrow$ \eval[p=.,vv@=1]{\[ \sum_{k=1}^N f(k) \]} [N=100,f(k)=1/k^3,{k}=1][4] As you can see, the summand \verb`f(k)` has been given explicit form in the vv-list – equated to \verb`1/k^3`. That means we need to give a preceding value to \verb`k` in the vv-list to avoid an unknown token message, hence the rightmost entry. But we don't want \verb`k=1` appearing in the final display, so we wrap \verb`k` in braces (see §\ref{subsec:evalVvSuppressVars}). Since the value \verb`k=1` applies only to the first term in the sum, to ensure it is not used for all terms, we enter \verb`vv@=1` in the settings option. This turns vv-recalculation mode on and ensures \verb`k=1` is overwritten by \verb`k=2`, \verb`k=3` and so on, and the vv-list recalculated each time. The final result is the same as before, although recalculating the vv-list at each step is a more resource-hungry process. The difference may not be marked for this example; with more complicated expressions it noticeably takes longer. Because it is necessary to activate this switch when using \emph{implicit} notations – like $f(k)$ in the example – rather than the explicit form of the function in the main argument, it seems natural to call \verb`vv@=1` \emph{implicit }mode and \verb`vv@=0` (the default) \emph{explicit }mode. Most calculations are explicit mode – the vv-list is evaluated only once.\emph{ } \subsection{Using degrees rather than radians} \label{subsec:settingsDegrees}You may find it more convenient to use degrees rather than radians with trigonometric functions. This can be switched on simply by entering a lowercase \verb`o` in the settings option. (The author hopes the charitable eye sees a degree symbol in the \verb`o`.) Thus \begin{centred} \verb`\eval[o]{$ \sin 30 $}` $\Longrightarrow$ \eval[o]{$ \sin 30 $}, \verb`\eval[o]{$ \arcsin 0.5 $}` $\Longrightarrow$ \eval[o]{$ \arcsin 0.5 $}. \end{centred} This is a \verb`0/1` switch, \verb`0` signifying \verb`off` or `don't use degrees', \verb`1` signifying \verb`on` or `do use degrees'. Out-of-the-box \texttt{numerica} assumes radians are being used, \verb`o=0`. As noted in §\ref{subsec:calcTrigonometricFunctions}, one can also append \verb`\degree` to a number (or a variable), making the \verb`o` switch unnecessary for the \emph{direct} functions (but always necessary if you want the \emph{inverse} functions to produce an answer in degrees). \subsection{Specifying a logarithm base} \label{subsec:settingsLogBase}If you wish to use \verb`\log` without a subscripted base in a particular calculation, then add an entry like \begin{verbatim} log = \end{verbatim} where \verb``~$\ne1$ to the settings option of the \verb`\eval` command. The \verb`` does not need to be an integer. It could be \verb`e` (if you object to writing \verb`\ln`) but is more likely to be $2$ or another small integer. If no value is specified, \texttt{numerica} assumes \verb`log=10`. \subsection{\textquoteleft Infinite\textquoteright{} sum and product settings} These settings, \verb`S+=`, \verb`P+=`, \verb`S?=`, \verb`P?=`, where the latter two are non-negative, determine when the stopping criterion for `infinite' sums and products applies. They are discussed in §\ref{sec:calcStoppingCriterion}. \section{Display-related settings} The following settings have no effect on the calculation but do change how the result is displayed. \subsection{Show/hide formula, \texttt{f}} \verb`\eval` automatically shows the formula in the result display if the \verb`env` setting is used to define the environment or \verb`\eval` wraps around the environment, but if the environment wraps around \verb`\eval`, display of the formula is suppressed. Either circumstance can be changed by entering \verb`f=0` to suppress display of the formula or \verb`f=1` to display the formula. \subsection{Environment settings, \texttt{env} etc.} \label{subsec:settingsEnvironmentSettings}The math environment in which a calculation is presented can be specified in three different ways: externally, with \verb`\eval` lying within the environment, or internally, either through the \verb`env` setting \begin{verbatim} env= \end{verbatim} or by explicitly writing the environment into the main argument containing the formula, although this last method is clumsy for anything other than \verb`$...$` or \verb`\(...\)` or \verb`\[...\]`. If multiple environments are – inadvertently or otherwise – specified, the outer environment takes precedence over the \verb`env` setting which takes precedence over the main-argument environment; this matter was discussed with examples in §\ref{sec:calcEnvironment-precedence}. \begin{table} \centering \caption{Initial values for environments}\label{tab:settingsEnvironment-defaults} \medskip{} \begin{tabular}{lccV{\linewidth}l} \toprule {\small\texttt{env}} & {\small rem/}{\small\texttt{arg}} & {\small\texttt{eq}} & {\small\texttt{vv}} & {\small\texttt{sep}}\tabularnewline \midrule {\small\texttt{\$}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{=}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 12muplus}}~\linebreak{} {\small\texttt{6muminus9mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{{\small\texttt{\textbackslash quad}}}\tabularnewline {\small\texttt{\textbackslash (}} & & & & \tabularnewline {\small\texttt{math}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{\textbackslash{[}}} & & {\small\texttt{=}} & \begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth} & {\small\texttt{\textbackslash{]}\textbackslash{[}}}\tabularnewline \cmidrule{1-1} {\small\texttt{displaymath}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{=}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{\textbackslash end\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}}~\linebreak{} {\small\texttt{\textbackslash begin\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}} \end{cellvarwidth}}\tabularnewline {\small\texttt{equation}} & & & & \tabularnewline {\small\texttt{equation{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{multline}} & \multirow{2}{*}{\begin{cellvarwidth}[t] \centering {\small\texttt{\textbackslash eval}}{\small{} in }\linebreak{} {\small{} }{\small\texttt{m'line}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{=}}} & \multirow{2}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{\textbackslash hfill\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{multline{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{multline}} & \multirow{2}{*}{\begin{cellvarwidth}[t] \centering {\small\texttt{m'line}}~\linebreak{} {\small in }{\small\texttt{\textbackslash eval}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{=}}} & \multirow{2}{*}{{\small\texttt{,\textbackslash\textbackslash (vv)}}} & \multirow{2}{*}{\begin{cellvarwidth}[t] {\small\texttt{\textbackslash end\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}}~\linebreak{} {\small\texttt{\textbackslash begin\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}} \end{cellvarwidth}}\tabularnewline {\small\texttt{multline{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{eqnarray}} & \multirow{2}{*}{} & \multirow{2}{*}{{\small\texttt{\&=\&}}} & \multirow{2}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{eqnarray{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{align}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{\&=}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{align{*}}} & & & & \tabularnewline {\small\texttt{aligned}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{flalign}} & \multirow{2}{*}{} & \multirow{2}{*}{{\small\texttt{\&=}}} & \multirow{2}{*}{{\small\texttt{,\&(vv)}}} & \multirow{2}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{flalign{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{gather}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{\&=\&}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 12muplus}}~\linebreak{} {\small\texttt{6muminus9mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{gather{*}}} & & & & \tabularnewline {\small\texttt{gathered}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{alignat}} & \multirow{3}{*}{{\small\texttt{2}}} & \multirow{3}{*}{{\small\texttt{\&=\textbackslash ;\&}}} & \multirow{3}{*}{{\small\texttt{,\textbackslash qquad\&(vv)}}} & \multirow{3}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{alignat{*}}} & & & & \tabularnewline {\small\texttt{alignedat}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{array}} & {\small\texttt{rcrl}} & {\small\texttt{\&=\&}} & {\small\texttt{,\&(vv)}} & {\small\texttt{\textbackslash\textbackslash}}\tabularnewline \cmidrule{1-1} {\small\texttt{cases}} & \multirow{2}{*}{} & \multirow{2}{*}{{\small\texttt{=}}} & \multirow{2}{*}{{\small\texttt{,\textbackslash quad\textbackslash hfill(vv)}}} & \multirow{2}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{dcases}} & & & & \tabularnewline \bottomrule \end{tabular} \end{table} Table~\ref{tab:settingsEnvironment-defaults} lists the environments that \verb`env` can be set to and that \verb`\eval` recognizes. It also lists the initial values of the settings \verb`arg`, \verb`eq`, \verb`vv` and \verb`sep`, designed to give sensible displays, without further intervention by the user, in many circumstances. (When the \verb`comma` package option is used, the comma leading the entries in the \verb`vv` column is replaced by a semicolon.) If you are using the \verb`env` setting, and want to change a value for one or more of these settings, then the changed value must be entered \emph{after} the \verb`env` setting to have any effect. There are other settings which inter-play with these environment settings but are not given initial values by the \verb`env` setting as \verb`arg`, \verb`eq`, \verb`vv` and \verb`sep` are, and so do not need to follow it in the settings option, but it is clearer and therefore good practice if they do. These are the punctuation settings \verb`p` and \verb`pp`, and the \verb`\}` setting applying only to \verb`aligned`, \verb`alignedat`, \verb`gathered`, \verb`cases`, \verb`dcases`, and \verb`array` environments – ones that require an enclosing math environment. The \verb`\}` setting gathers the results of a multi-formula display within a large right delimiter (right brace by default); it is usually followed by the vv-list and allows the results of a multi-formula calculation to be collectively numbered rather than individually. \subsubsection{\texttt{arg}} The \verb`array` and \verb`alignat` group of environments require an argument, as in \verb`\begin{array}{arg}...` and \verb`\begin{alignat}{arg}...`. For recognized environments the pre-set value of \verb`arg` is shown in the second column of Table~\ref{tab:settingsEnvironment-defaults}. Note that the use of \verb`arg` environments is possible with \verb`\eval` \emph{only} when used with the \verb`env` setting; otherwise the \verb`{arg}` is misinterpreted and will generally cause an error, as in the following, with its peculiar error message \begin{verbatim} \[ \eval[ff]{ \begin{array}{rcll} \sin x, \cos x, \tan x \end{array}}[x=\pi/6] \] \end{verbatim} $\Longrightarrow$ \[ \eval[ff]{ \begin{array}{rclr} \sin x, \cos x, \tan x \end{array}}[x=\pi/6] \] \noindent The problem does not arise when the \verb`env` setting is used: \begin{verbatim} \[ \eval[env=array,ff]{ \sin x, \cos x, \tan x }[x=\pi/6][*] \] \end{verbatim} $\Longrightarrow$ \[ \eval[env=array,ff]{ \sin x, \cos x, \tan x }[x=\pi/6][*] \] \noindent In this case, with the pre-set \verb`arg=rcrl`, the formulas are right-aligned, the equality signs are centred, the numerical results are right-aligned and the vv-lists are left-aligned. These alignments can be changed with the \verb`arg` setting, but this must \emph{follow} the \verb`env` setting for the changes to have any effect. \subsubsection{\texttt{eq}} \label{subsec:settingsRelationSymbol}Throughout this document, \emph{formula=result} displays have used the equality sign between the two sides. Most of the results however have been approximate. If you want a different relation symbol in the display, enter \begin{verbatim} eq= \end{verbatim} in the settings option. For example, \begin{centred} \verb`\eval[eq=\approx]{$ \pi $}[4]` $\Longrightarrow$ \eval[eq=\approx]{$ \pi $}[4]. \end{centred} If the \verb`approx` package option is being used, note that \verb`eq` defaults to \verb`=` , so that – say – for a calculation with an integer answer for which $\approx$ would be inappropriate it suffices just to enter \verb`eq` to obtain $=$ between formula and result. A main use of this setting is with environments with alignment where \verb`&=` and \verb`&=&` are natural values for \verb`eq`; see below, §\ref{subsec:settingsEnvironmentSettings}. If the \verb`env` setting is being used then the \verb`eq` setting must \emph{follow} it to have any effect. \subsubsection{\texttt{vv}} \label{subsec:settingsVvDisplayChangeLocal}In many of the examples in this document the vv-list has been displayed following the result. It is wrapped in parentheses following a comma and a space. (A semicolon replaces the comma if the \verb`comma` package option is used.) These elements – comma, space, parentheses – can all be changed by entering \begin{verbatim} vv= \end{verbatim} in the settings option. For example \begin{verbatim} vv=;\mskip 12mu plus 6mu minus 9mu(vv) \end{verbatim} will result in a semicolon immediately following the numerical result followed by an elastic space followed by the actual vv-list – replacing the placeholder \verb`vv` – enclosed in parentheses. No full stop is inserted after the closing parenthesis because the \verb`\eval` command may occur in the middle of a sentence (and the \verb`p` setting is available for such punctuation in displaystyle contexts). For inline use, the elasticity of the space becomes relevant when \TeX{} is adjusting individual lines to fit sentences into paragraphs and paragraphs into pages. If a comma were to replace the semicolon in the suggested vv-list spec., it would need to be entered in braces or as \verb`\comma`, since the settings option is a comma-separated list. In displaystyle settings, some shrink in the space is a good idea to accommodate a long formula or many variables in the vv-list. For a particular calculation with a surprising result, one might specify \verb`vv=?!` with no vv-list shown (since the \verb`vv` placeholder is not used on the right): \begin{centred} \verb`\eval[vv=?!]{$ \pi $}[\pi=3]` $\Longrightarrow$ \eval[vvi=?!]{$ \pi $}[\pi=3] \end{centred} Different formats for vv-list display are appropriate for different environments. Those with alignment, like the AMS environments, may have an alignment token \verb`&` following a comma (or semicolon) before display of the vv-list proper; see below, §\ref{subsec:settingsEnvironmentSettings} and Table~\ref{tab:settingsEnvironment-defaults}. If the \verb`env` setting is being used then the \verb`vv` setting must \emph{follow} it to have any effect. \subsubsection{\texttt{sep}} \label{subsec:settingsEnvironments-sep}Displaying the results of a multi-formula calculation means separating the displays for each result. The \verb`sep` setting specifies the tokens inserted between each display: \begin{verbatim} sep = \end{verbatim} where \verb`` may be something like \verb`\quad` for an inline environment or \verb`\\` in a multi-line environment, see Table~\ref{tab:settingsEnvironment-defaults}. For \verb`multline` and \verb`multline*` different values are assigned depending as \verb`\eval` is wrapped by or wraps the environment. The function of the \verb`sep` setting overlaps that of the \verb`pp` setting, but it proves more flexible to keep them separate. Since \verb`env`-ironments come with pre-set values of \verb`sep`, if both settings are being used, the \verb`sep` setting must \emph{follow} \verb`env` for it to have any effect. \subsubsection{\texttt{p}, \texttt{pp}} \label{subsec:settingsPunctuation}As noted in the discussion at §\ref{subsec:introPunctuation}, punctuation of the display of a result is straightforward when the \verb`\eval` command is used in inline contexts but requires use of a setting in displaystyle environments. The setting \begin{verbatim} p = \end{verbatim} places {\ttfamily\verb``} after the display of everything else but within the environment delimiters. The default punctuation mark is the comma so that entering \verb`p` alone will produce a comma in the appropriate place. Since the settings option is a comma-separated list, this saves having to write \verb`p={,}`. Note that {\ttfamily\verb``} need not be a single-character punctuation mark: \begin{centred} \verb`\eval[p=\ \text{(but no 8!)}]{\[ \frac{1}{81} \]}[9]` $\Longrightarrow$ \eval[p=\ \text{(but no 8!)}]{\[ \frac{1}{81} \]}[9] \end{centred} For multi-formula commands punctuation may be desired not just after the final result (the \verb`p` setting) but also after the intermediate results. For these, use the setting \begin{verbatim} pp = \end{verbatim} Like \verb`p`, the \verb`pp` setting defaults to a comma to avoid having to write \verb`pp={,}`. See the examples at §\ref{subsec:intoMultiFormulaPunctuation} and throughout this document. \subsubsection{\texttt{\textbackslash\}}} \label{subsec:settingsEnvironments-=00005C=00007D}Some environments must lie within another math environment to be used. These environments – the AMS \verb`-ed` environments, the \verb`cases` and \verb`dcases` environments, and the \verb`array` environment – allow one to `collect' results of a multi-formula calculation within a large right delimiter – usually a right brace – and follow that with the vv-list. The setting for this is \verb`\}`: \begin{verbatim} \} = \end{verbatim} Here \verb`` is either a single token or a brace group defining a space between the numerical results and the right delimiter. \verb`` is any right delimiter that responds to the command \verb`\right` of a \verb`\left` \verb`\right` pair; that includes a dot, \verb`.` , if you want no delimiter. The default specification is \verb`\}=\ \}`. In the following example an \verb`alignedat` environment is used to align numerical results containing a minus sign. The \verb`pp` and \verb`p` settings place commas after the results, not after the vv-list. The full stop there is manually inserted after the number-format option (and before the \verb`\]`). The example shows how to suppress the needless repetition of the vv-list that otherwise accompanies display of a multi-formula result. If so wished, the three calculations could be collectively numbered by a single equation number. \begin{verbatim} \[ \eval[env=alignedat,pp,p,\}=.,vv=\qquad(vv),ff] { \sin nx, \cos (n+1)x, \tan x } [n=2,x=\pi/6][*]. \] \end{verbatim} $\Longrightarrow$ \[ \eval[env=alignedat,pp,p,\}=.,vv=\qquad(vv),ff] { \sin nx, \cos (n+1)x, \tan x } [n=2,x=\pi/6][*]. \] \section{Deprecated and obsolete settings} \label{sec:settinsDeprecatedObsoleteOptions} \begin{description} \item [{\texttt{vvi,~vvd}}] These settings have been superseded by the \verb`vv` setting as a result of the enhanced treatment of environments in version 3.0.0 of \texttt{numerica}; see immediately above. Both \verb`vvi` and \verb`vvd` settings are now treated as alternative (but deprecated) names for \verb`vv`. \item [{\texttt{{*}}}] In version $2$ of \texttt{numerica} this key was used to suppress equation numbering when the \verb`vvd` specification contained a newline character. If \verb`\\` was present in \verb`vvd`, it triggered replacement of whatever math delimiters were enclosed by the \verb`\eval` command with a \verb`multline` environment. The star {*} then converted the \verb`multline` into a \verb`multline*`. This is all now superseded by the enhanced treatment of environments. \item [{\texttt{()}}] Earlier versions of \texttt{numerica} used this setting to adjust how `expansively' the arguments of trigonometric functions were read, with the arguments of such functions in Fourier series in mind. Version 3.0.0 of \texttt{numerica} has dispensed with the setting and now recommends using \LaTeX{} braces to delimit such arguments. See the general discussion at §\ref{subsec:evalBraced-groups}, and more specific discussion at §\ref{subsec:calcComplicated-arguments}. \item [{\texttt{reuse}}] In earlier versions of \texttt{numerica} this setting determined exactly what was saved with the next \verb`\reuse` command. Now only the `naked' numerical result is saved, although it may be in scientific notation or fraction form; see §\ref{subsec:supplReuseEvalSetting}. \end{description} \chapter{Supplementary commands} \label{chap:Supplementary-commands}This chapter introduces four commands, \verb`\nmcInfo` (met already in relation to infinite sums), \verb`\nmcMacros`, \verb`\nmcConstants` and \verb`\nmcReuse`, supplementary to the principal command \verb`\nmcEvaluate`. They use the same machinery as \verb`\nmcEvaluate` and so have the same syntax. If all arguments are present it is \begin{centred} \noindent\verb`\nmc*[settings]{main arg}[vv-list][rounding]` \end{centred} where \verb`` is one of \verb`Info`, \verb`Macros`, \verb`Constants` and \verb`Reuse`. All four commands have short-name forms: \verb`\info`, \verb`\macros`, \verb`\constants`, \verb`\reuse`. Generally the final two optional arguments will not be used. The user should be aware of this if following a command with a square bracketed expression – the expression will be absorbed without trace unless it is preceded by, for example, an empty brace pair. Because the commands share the machinery of \verb`\nmcEvaluate`, the \verb`dbg`, \verb`view` and functional settings discussed in the previous chapter (Chapter~\ref{chap:settingsSettings}) for the \verb`\eval` command are also available for these commands, although many will be without effect. The starred form of command is available in all four cases and in all cases produces a pure number. If both star ( \verb`*` ) and \verb`view` are used at the same time, the \verb`view` setting prevails over starring. \section{Feedback on \textquoteleft infinite\textquoteright{} processes:\texttt{ \textbackslash nmcInfo}} \label{sec:supplInfo}Used after the evaluation of an `infinite' process, the \verb`\nmcInfo` command, or its short-name form \verb`\info`, will tell you how many terms or factors or other operations\footnote{It also applies to the commands \texttt{\textbackslash nmcIterate }and \texttt{\textbackslash nmcSolve} from the \texttt{numerica-plus }package.} were needed to arrive at the result.The main argument contains an identifier for the `infinite' process: \begin{verbatim} \nmcInfo{} \end{verbatim} (or, using the short-name form, \verb`\info{}`) where, at this stage, \verb`` is either \verb`sum` or \verb`prod`. The display, as we have seen in earlier examples, is a number followed by a space then a descriptor. For \verb`sum` and \verb`prod` the descriptors are \verb`terms` and \verb`factors` respectively. Starring \verb`\nmcInfo` – \verb`\nmcInfo*{arg}` or \verb`\info*{arg}` – suppresses the descriptor and leaves only the number. As an example, let's test `the hard way' a standard identity, $\cosh^{2}x-\sinh^{2}x=1$. We know that $\cosh x=\sum_{n=0}^{\infty}\frac{x^{2n}}{(2n)!}$ and $\sinh x=x\prod_{k=1}^{\infty}\left(1+\frac{x^{2}}{k^{2}\pi^{2}}\right)$. The difference of their squares should be $1$: \begin{verbatim} \eval{\[ \left[\sum_{n=0}^{\infty} \frac{x^{2n}}{(2n)!} \right]^2- \left[x\prod_{k=1}^{\infty} \left(1+\frac{x^{2}}{k^{2}\pi^{2}}\right) \right]^2 \]}[x=1][3] \info{sum},\quad \info{prod}. \end{verbatim} $\Longrightarrow$ \eval{\[ \left[\sum_{n=0}^{\infty} \frac{x^{2n}}{(2n)!}\right]^2- \left[x\prod_{k=1}^{\infty} \left(1+\frac{x^{2}}{k^{2}\pi^{2}}\right) \right]^2 \]}[x=1][3] \info{sum},\quad\info{prod}. Nearly right. Obviously the product converges only slowly which is where the error comes from (see the discussion in §\ref{sec:calcStoppingCriterion}, where we needed the extra rounding setting \texttt{P+=3} and $350$ factors to get a correct 3-figure value). The point of the example is to show the information command being used for both sum and product in the one evaluation. One does not exclude the other. The starred form of the \verb`\info` command suppresses the descriptor (`terms' or `factors') and gives a purely numerical result: \begin{verbatim} \eval{$ \sum_{k=0}^{\infty}\binom \alpha k x^k $}[x=1/2,\alpha=3],\\ \\ requiring \eval{$ \info*{sum}-1 $}\ additions. \end{verbatim} $\Longrightarrow$ \eval{$ \sum_{k=0}^{\infty}\binom \alpha k x^k $}[x=1/2,\alpha=3],\\ \\ requiring \eval{$ \info*{sum}-1 $}\ additions. In fact the starring is unnecessary in this example since all nested commands are now treated as if they were starred. \subsection{Errors} Should the \emph{wrong} argument be used in the \verb`\nmcInfo` command, no harm is done: \begin{verbatim} \eval{$ \sum_{k=0}^{\infty}\binom \alpha k x^k $} [x=1/2,\alpha=3], \ \info{prod} \end{verbatim} $\Longrightarrow$ \eval{$ \sum_{k=0}^{\infty}\binom \alpha k x^k $}[x=1/2,\alpha=3],\ \info{prod}.\medskip{} $119$ \emph{factors}? We were evaluating a sum but used \verb`prod` as the argument of the \verb`\info` command which remembers a previous result, the last time \verb`prod` was used as its argument. Changing the argument from \verb`prod` to \verb`sum` reveals the correct number of \emph{terms}. Should a non-existent argument be used, an error message is generated: \begin{verbatim} \eval{$ \sum_{k=0}^{\infty}\binom \alpha k x^k $}[x=1/2,\alpha=3], \\ \info{Fred} \end{verbatim} $\Longrightarrow$ \eval{$ \sum_{k=0}^{\infty}\binom \alpha k x^k $}[x=1/2,\alpha=3],\\ \\ \info{Fred} \subsection{\texttt{view} setting} Only two settings seem relevant for \verb`\info`: the \verb`dbg` and \verb`view` settings. Rather than use the obscure \verb`dbg=` (which is possible), it suffices to enter \verb`view` in the settings option: \begin{centred} \verb`\info[view]{}` $\Longrightarrow$ \info[view] {} \end{centred} The result is a display of all the current values of all the `infinite' processes available. (Further processes become available if the \texttt{numerica-plus} package is used.) The mandatory but empty braces can be filled with \verb`sum`, \verb`prod` or even \verb`Fred` but it makes no difference; the display is always of the current values of all `infinite' processes \texttt{numerica} knows about. If there has been no sum or product evaluated, the displayed value is conventionally shown as zero. \section{User-defined macros: \texttt{\textbackslash nmcMacros}} \label{sec:supplMacros}The \verb`\nmcMacros` command was prompted by a question on \TeX{} Stack Exchange.\cprotect\footnote{See \url{https://tex.stackexchange.com/questions/602993/use-macros-in-numerica-vv-list/602998#602998}} Some time later the maintainer of the \verb`mandi` package approached me with a similar problem. Suppose one has defined a macro to contain a value, say \begin{itemize} \item \verb`\def\myvalue{0.35}`, or \item \verb`\newcommand\myvalue{0.35}`, or \item \verb`\NewDocumentCommand\myvalue{}{ 0.35 }`. \end{itemize} (If you're using the document processor \LyX{} then there is good reason to prefer \verb`\gdef` to define your macro, \verb`\gdef\myvalue{0.35}`; see Chapter~\ref{sec:miscLyX}). After one of these commands, \verb`\myvalue` is now known to \LaTeX , but it is not known to \texttt{numerica}. The quantities \texttt{numerica} \emph{does }know about are variables in the vv-list of an \verb`\eval` command, and those \LaTeX{} (and \texttt{amsmath} and \texttt{mathtools}) commands used for writing mathematical expressions. These quantities are stored in \texttt{numerica} in structures called property lists. Since \verb`\myvalue` is not – yet – recorded in these lists putting \verb`x=\myvalue` in the formula or vv-list of an \verb`\eval` command will produce an `Unknown token' error message: \begin{verbatim} \NewDocumentCommand \myvalue {} { 0.35 } \eval{ \myvalue } \end{verbatim} $\Longrightarrow$ \NewDocumentCommand \myvalue {} {0.35} \eval{ \myvalue } From version 2 of \texttt{numerica}, a command \verb`\nmcMacros` is available to register macros and their values with the property lists used internally by \texttt{numerica}. The macro must have been defined earlier in the document or in a supporting package. Using \verb`\nmcMacros` (or \verb`\macros` in its short-name form) is simple. If you have a list of macros you wish to use in \texttt{numerica}, enter them in a comma (or a semicolon list if the decimal comma is being used) in the mandatory argument of the command. The \verb`ff` setting necessary for a multi-formula calculation in \verb`\eval` is implicit for \verb`\nmcMacros` – it does not need to be added: \begin{verbatim} \nmcMacros{ \macro1, \macro2, … } \nmcMacros{ \macro1; \macro2; … } \end{verbatim} \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% Since no decimal numbers are involved, no ambiguity would arise from using a comma separator even when the \verb`comma` package option is used but consistency with multi-formula calculations in \verb`\eval` suggests that a semicolon should be – and is – insisted upon unless explicitly countermanded by entering \verb`ff=` in the settings option of the \verb`\macros` command.\end{shaded}% \end{minipage}\medskip{} \noindent Multiple \verb`\macros` commands can be used in a document. If the command is placed in the preamble (\emph{after} the definition of the macros)\emph{ }then the user-defined macros and their values are available throughout the document, otherwise they are available from the position of the \verb`\macros` statement. However, it is not necessary for macros to be defined in the \emph{current} document provided they are defined and accessible from some other loaded \LaTeX{} package. But always an \verb`\nmcMacros` (or \verb`\macros`) command is required to register them with \texttt{numerica} for use in \verb`\eval`. \subsection{What can be stored in a macro?} Generally a user-defined macro will store a number. This macro might well be defined in an external package – for example the \verb`mandi` package defines a large number of macros containing the values of physical constants, some fundamental like the speed of light, others contingent like the earth–moon distance. If the \verb`mandi` package is loaded\footnote{Maintainer Joe Heafner explains that `mandi' abbreviates `matter and interactions' after a physics textbook of that name.} then writing, for instance, \begin{verbatim} \macros{ \electronmassprecisevalue, \protonmassprecisevalue } \end{verbatim} will make these two macros available for use in \texttt{numerica}. One could then write in the vv-list of an \verb`\eval` command \begin{verbatim} m_e=\electronmassprecisevalue, m_p=\protonmassprecisevalue \end{verbatim} which would allow (among other things) calculation of the mass ratio $m_{p}/m_{e}$ of proton to electron. (The length of name of some of the macros in the \verb`mandi` package has a pedagogical purpose, but makes them unwieldy for direct use in mathematical calculations.) \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \noindent In version 2 of \texttt{numerica}, where the \verb`\macros` command was introduced, if the first token in a macro definition was expandable (like \verb`\sin` expanding to $\sin$ or \verb`\sum` expanding to $\sum$) it was necessary to ensure there was a preceding space. If the first token was a digit, there was no problem. From version 3.0.0 this is no longer the case. A leading space may or may not be included; it doesn't matter. I thank \noun{David Carlisle} for the routine that solved this irritant.\footnote{\url{https://tex.stackexchange.com/questions/683578/storing-the-unknown-contents-of-a-macro-in-a-clist}}\end{shaded}% \end{minipage} \subsubsection{Macros containing formulas } Numbers are not the only quantities that can be stored in a macro for use in \texttt{numerica}. In fact any mathematical expression that can be \verb`\eval`-uated can be stored in a macro: \begin{verbatim} \NewDocumentCommand \mysumC {} { \sum_{n=1}^{100}1/n - \ln 100 } \macros{ \mysumC } \eval{$ \mysumC $}[4] \end{verbatim} $\Longrightarrow$ \NewDocumentCommand \mysumC {} { \sum_{n=1}^{100}1/n - \ln 100 } \macros{ \mysumC } \eval{$ \mysumC $}[4], \medskip{} \noindent (to be compared with Euler's constant \eval{$ \gamma $}[4] – obviously many more terms are needed). The \verb`\eval` command wraps around math delimiters in the example. Hence the result is presented in the form \emph{formula=result}. In that presentation, note how \verb`\mysumC` displays as the formula it contains. \subsubsection{vv-list} In the example it would be nice to be able to vary the number of terms summed. This is easily done by using a vv-list in the \verb`\macros` statement: \begin{verbatim} \NewDocumentCommand \mysumN {} { \sum_{n=1}^{N}1/n - \ln N } \macros{ \mysumN }[N=150] \eval{$ \mysumN $} \end{verbatim} $\Longrightarrow$ \NewDocumentCommand \mysumN {} { \sum_{n=1}^{N}1/n - \ln N } \macros{ \mysumN }[N=150] \eval{$ \mysumN $}.\medskip{} \noindent\texttt{numerica} needs a definite value to store; it does not store the formula as such. To give \verb`\mysumN` a definite value, give the variable \verb`N` a value. This is done in the vv-list added to the \verb`\macros` statement: \verb`N=150`. In this way a definite value is stored in \texttt{numerica} against the macro \verb`\mysumN`. The definition of the macro is unaffected. If a new value is given to \verb`N` in the \verb`\macros` statement (which is the point of using a variable), the old value is overwritten and the new value is used in subsequent calculations. \subsection{Seeing what macros are available} Perhaps your document has a number of \verb`\nmcMacros` statements scattered through it and you want to remind yourself of what exactly has been stored. \verb`\nmcMacros` has the \verb`view` setting for this purpose. Writing \begin{centred} \verb`\macros[view]{}` $\Longrightarrow$ \macros[view]{} \end{centred} produces a list of all macros registered with \texttt{numerica} and their values, as you can see. If the braced argument is not empty, the display is slightly modified: \begin{verbatim} \def\mydef{ \sin(m\pi/n) } \newcommand\mynewcmd{ \cos(m\pi/n) } \macros[view]{ \mydef,\mynewcmd }[m=3,n=18] \end{verbatim} $\Longrightarrow$ \def\mydef{ \sin(m\pi/n) } \newcommand\mynewcmd{ \cos(m\pi/n)} \macros[view]{ \mydef,\mynewcmd }[m=3,n=18] \noindent\verb`\mydef` and \verb`\mynewcmd` have been added to those available for use in \texttt{numerica}. \subsection{Freeing macros from storage} Rather than cluttering \texttt{numerica}'s property lists with no-longer-needed macros, it is possible to remove them from there with the \verb`free` setting. This has no effect on the \LaTeX{} definition of the macro. It merely `de-registers' the macro with \texttt{numerica}. \begin{centred} \verb`\macros[free,view]{ \mysumC }` $\Longrightarrow$ \macros[free,view]{ \mysumC } \end{centred} If you want to free \emph{all} macros registered with \texttt{numerica} use an empty main argument with the \verb`free` setting. For an example, see just below. \subsection{Counting how many macros are available} You can count how many macros are currently registered with \texttt{numerica} by starring the \verb`\nmcMacros`~command: \begin{centred} \verb`\macros*{}` $\Longrightarrow$ \macros*{}. \end{centred} If the braced argument is not empty, the list of macros it contains will be added to those registered with \texttt{numerica} and included in the overall count. Note that the \verb`view` setting prevails over starring if both are used. The star can also be used with the \verb`free` setting. As mentioned above, if the main argument is empty, then \emph{all} macros are freed: \begin{centred} \verb`\macros*[free]{}` $\Longrightarrow$ \macros* [free]{}. \end{centred} \subsection{Errors} \label{subsec:supplMacrosErrors}If a macro is used in a \verb`\macros` statement but has not been defined earlier in the document or a supporting package it will cause an error: \begin{centred} \verb`\macros{ \mymacro }` $\Longrightarrow$ \macros{\mymacro } \end{centred} \noindent An undefined macro used in an \verb`\eval`-uation will cause an `Unknown token' message in \texttt{numerica}. The solution in both these cases is (obviously) to define the macro. If a macro is defined but the \verb`\macros` statement overlooked and the macro used in an \verb`\eval`-uation, it will generate an `Unknown token' message. If your macro stores a formula with variables, and you forget to give those variables values in the \verb`\macros` statement that will produce a message, for instance: \begin{verbatim} \def\mysumk{ \sum_{n=1}^k n } \macros{ \mysumk } \end{verbatim} $\Longrightarrow$ \def\mysumk{ \sum_{n=1}^k n } \macros{ \mysumk } \noindent In this case the `where' part of the message is specific, but more usually will be \verb`macros command`. And of course there can be `all the usual suspects' discussed in Chapter~\ref{chap:errorsErrors}. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \subsubsection{Display of macros} \label{subsec:supplMacrosDisplay}Once a macro is known to \LaTeX{} it can be used as a variable name. If it is entered as such on the left of an equals sign in the vv-list, \verb`\eval` will treat it as a variable name. As with multi-token variables (§\ref{subsec:evalDon't-do-this!}), this fact can be abused. In the following example the macro is defined in \LaTeX{} but there is no \verb`\macros` statement. \begin{verbatim} \def\mymac{1} \eval[vv=\,???]{$ \mymac+\mymac $}[\mymac=2] \end{verbatim} $\Longrightarrow$ \def\mymac{1} \eval[vv=\,???]{$ \mymac+\mymac $}[\mymac=2] Do not define a macro containing some value and then use it as a variable name for a different value. Macros display as their content. The value ($2$) assigned to a variable name (\verb`\mymac`) for calculational purposes in \verb`\eval` and how that variable name displays in \LaTeX{} are separate things. It is up to the user not to abuse this fact.\end{shaded}% \end{minipage} \subsection{Rounding value} \label{subsec:supplMacrosRounding}Values are stored to $16$ significant figures (if available). In most cases appending a rounding value to a \verb`\macros` statement has no effect on the value stored. In the following example note the \verb`o` setting, meaning the sine reads angles in degrees: \begin{verbatim} \NewDocumentCommand\testi{}{ \sin 60 } \NewDocumentCommand\testii{}{ \sin 60 } \macros[o]{ \testi }[10] \macros[o]{ \testii }[3] \macros[view]{} \end{verbatim} $\Longrightarrow$ \NewDocumentCommand\testi{}{ \sin 60 } \NewDocumentCommand\testii{}{ \sin 60 } \macros[o]{ \testi }[10] \macros[o]{ \testii }[3] \macros[view]{} \noindent Despite the different rounding values in the \verb`\macros` statements the same $16$ figures are stored in both \verb`\testi` and \verb`\testii`. For the \verb`\eval` command, rounding values specify how results are \emph{displayed}. In general the rounding value matters \emph{after}, not during, the calculation. Only for infinite sums or products is this otherwise. (Although fraction-form output from \verb`\eval` also depends on the rounding value, that is not relevant here.) For infinite sums or products the rounding value is used to determine when to stop adding further terms or factors. The same is true of the \verb`\macros` command. Only if a macro contains an infinite sum or product does the rounding value become relevant. Sixteen figures are still stored, but most of them will be `wrong' since the infinite sum or product has stopped early, after only a finite number of terms or factors. Exactly how many of the first few figures are correct depends on the rounding value. An example may clarify the matter. \begin{verbatim} \macros[free]{} \def\zetaiii{ \sum_{n=1}^\infty 1/n^3 } \macros[view]{ \zetaiii }[3] \info{sum} \macros[view]{ \zetaiii }[6] \info{sum} \end{verbatim} $\Longrightarrow$ \macros[free]{} \def\zetaiii{ \sum_{n=1}^\infty 1/n^3 } \macros[view]{ \zetaiii }[3] \info{sum} \macros[view]{ \zetaiii }[6] \info{sum} \emph{HMF }Table 23.3 tells me that $\zeta(3)=1.202056903159594\dots$ The different rounding numbers have restricted the infinite sums to the very finite $47$ and $468$ terms respectively. Although $16$ figures are stored, only the first few are correct, three more for rounding value $6$ than for rounding value $3$. \section{User-defined constants:\texttt{ \textbackslash nmcConstants}} \label{sec:supplConstants}As noted much earlier in this document (§\ref{subsec:evalBuilt-in-Constants}), there are five built-in constants: \verb`\pi`, \verb`e`, \verb`\phi`, \verb`\gamma` and \verb`\deg`, but a user may well want to define their own constant or constants. There are contexts where it would make sense to permanently record fundamental constants like the speed of light or Planck's constant, or more down-to-earth constants like the acceleration due to gravity or the viscosity of water, rather than having to enter them in the vv-list for each calculation. Or a parameter might be held constant for a particular problem or class of problems where other variables change – for example triangles of constant perimeter but varying sides. This is the purpose of the \verb`\nmcConstants` command. The symbols used to denote constants are subject to exactly the same constraints and freedoms as the symbols used to denote variables. They might be single latin letters like \verb`c` (e.g.\ $c=3\times10^{8}$), or greek letters like \verb`\alpha` (e.g.\ $\alpha=1/137)$, or multi-token combinations like the Rydberg constants \verb`R_\infty` or \verb`R_{\mathrm{H}}` from atomic physics, or \verb`\mu_0` and \verb`\epsilon_0` used to denote the permeability and permitivity of free space, or personal constants like \verb`total` of no wider significance. \texttt{numerica} handles all these different forms of constant with the command \verb`\nmcConstants`, where the main argument is a comma-list of \emph{const=value} statements: \begin{verbatim} \nmcConstants{ const1=value1, const2=value2, ... , const-n=value-n } \end{verbatim} \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% When the \verb`comma` package option is used and the decimal point is a comma, the default item separator in \verb`\nmcConstants` is the semicolon. Alternatively and irrespective of the choice of decimal point, a user can specify a separator with the setting \verb`ff=`, e.g. \verb`ff=|`, and use that.\end{shaded}% \end{minipage}\medskip{} This is the simplest use – each constant is assigned a numerical value. But it is easy to envisage situations where it would be convenient to have a constant with value $1/\sqrt{2\pi}$ say, or another with value $e^{\tfrac{\pi}{2}}$, and so on. That is easy: simply put the expession for the value on the right: \begin{verbatim} \constants{ a=1/\sqrt{2\pi},b=e^{\tfrac\pi2} } \end{verbatim} where the short(er)-name form \verb`\constants` has been used. Or the values could be expressions depending on parameters: \begin{verbatim} \constants{ s=\tfrac12(a+b+c) }[a=3,b=5,c=7] \end{verbatim} Some constants might depend on earlier constants in the list: \begin{verbatim} \constants{ A=\sqrt{s(s-a)(s-b)(s-c)}, s=\tfrac12(a+b+c) }[a=3,b=5,c=7] \end{verbatim} Or the values could involve an `infinite' process, requiring a rounding value: \begin{verbatim} \constants{ \zeta=\sum_{n=1}^\infty(1/n^k) }[k=4][5] \end{verbatim} In this, although $16$ figures will be stored, only the first few will be accurate, the precise number depending on the value of \verb`k` and the rounding value (\verb`5` in the example); see the discussion on this issue for user-defined macros above. \subsection{New list \emph{replaces} old} A particular group of constants may be relevant only to a particular part of a document. Another part of the document may use other constants. By default, a second list of constants \emph{replaces }the first list. Thus each of the \verb`\constants` statements above would replace the previous one. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% There is a technical reason for this. For each calculation all \emph{multi-token} constants are added internally to the start of the vv-list of the \verb`\eval` command. Even if the vv-list is empty, this is still the case since the formula might well use constants. As for multi-token variables (see §\ref{subsec:evalVariableNames}), multi-token constants are mapped internally to single tokens. This occurs afresh for each calculation which will require not only this mapping from multi- to single tokens but the evaluation of a vv-list that includes the multi-token constants. It seems safer to make the default behaviour replacement of one constant list by another, rather than cumulating them. \end{shaded}% \end{minipage} \subsection{Adding constants to a list} Despite which there will be occasions when adding new constants to an existing list is desired. This is easily done with the \verb`add` setting. For instance, \begin{verbatim} \nmcConstants[add]{ \sigma=5.67\times10^{-8}, k_B = 1.381\times10^{-23} } \end{verbatim} would add \verb`\sigma` and \verb`k_B` to the current list. The presence of the \verb`add` setting triggers appending rather than replacement. \subsection{Examples of use} \subsubsection{Example 1: atomic constants} In the following example, the values of various atomic constants are taken from the \verb`mandi` package. I use two \verb`\constants` statements in order to show the use of the \verb`add` setting. I've also included a \verb`view` setting in the second \verb`\constants` statement. The constants are used to calculate the fine-structure constant \verb`\alpha` in the vv-list of the \verb`\eval` command, and its well-known reciprocal (close to $137)$ in the main argument. Note that the constants do not need to be entered in the vv-list of the \verb`\eval` command. Their values are available from the \verb`\constants` statements. \begin{verbatim} \constants{ c=2.99792458\times10^{8}, h=6.62607015\times10^{-34}, e=1.602176634\times10^{-19} } \constants[view,add] { \epsilon_0=8.854187817\times10^{-12} } \eval{$ 1/\alpha $}[\alpha=e^2/2\epsilon_0hc] \end{verbatim} $\Longrightarrow$ \constants{ c=2.99792458\times10^{8}, h=6.62607015\times10^{-34}, e=1.602176634\times10^{-19} } \constants[view,add] {\epsilon_0=8.854187817\times10^{-12} } \eval{$ 1/\alpha $}[\alpha=e^2/2\epsilon_0hc]. The \verb`view` setting produces a now familiar kind of display. It shows that the three-token \verb`\epsilon_0` (the control sequence \verb`\epsilon`, the underscore \verb`_` and the digit \verb`0`) has been replaced by \verb`\nmc_p` – which may look as if it is also three tokens but is in fact a single control sequence. \subsubsection{Example 2: local constants} Long ago, when there were such creatures as reference librarians, I was asked about a school physics project along these lines. A\emph{ car is travelling at 50 km/hr when it hits a lamppost. The bonnet crumples 1 metre and the car comes to an immediate halt. Although she herself is wearing a seat-belt, a woman in the passenger cabin is holding her 5 kg baby. Does the baby survive?} The enquirer was familiar with the equations describing constant acceleration, \[ x=ut+\tfrac{1}{2}at^{2},\quad\text{and}\quad v^{2}-u^{2}=2ax, \] and Newton's second law, $F=ma$, force equals mass times acceleration. The question was really about understanding these laws and how to think with them. Here, $s$ is the distance travelled in time $t,$ with initial speed $u$ at $t=0$, speed $v$ at time $t$, and constant acceleration $a$ – a deceleration in this case. The given data provide our constants: distance $x=1$ metre, initial speed $u=1000*50/(60*60)=(10/36)*50$ metres per second, final speed $v=0$. To estimate whether the woman can hold on to her baby, we will need to make a comparison with forces we have personally experienced. Most of us have tried lifting someone else, so let's use a characteristic human weight as our test mass. Thus, we have the (baby's) mass $m=5$ kilograms, and a test mass, $M$ say, which we will leave as a variable. But dealing with weight, we will need the acceleration due to gravity. For the kind of rough estimating we are doing, $g=10$ metres per second per second will be an adequate approximation. \begin{verbatim} \constants{ x=1,v=0,u=(10/36)50,m=5,g=10 } \end{verbatim} The deceleration experienced by the woman is found from the second equation of constant acceleration, $a=(v^{2}-u^{2})/2x$. Even if the deceleration isn't constant this will give an estimate of its magnitude. (If some of the deceleration is less than this $a$, some must be greater.) This is also the deceleration experienced by the baby as long as the woman holds onto her. Hence the magnitude of the force exerted by the baby on the woman's arms is $ma=m(v^{2}-u^{2})/2x=-mu^{2}/2x$ which we want to compare with our test force, say that required to lift $M=70$ kilograms, which was once considered the mass of an average western adult male (but is doubtless a considerable underestimate now). Hence the test force is $Mg$. Let's do the calculations. (I have altered the \verb`\constants` statement to allow for a later comparison with the effect of a small increase in speed.) \begin{verbatim} \constants{ x=1,u=(10/36)U,m=5,g=10 }[U=50] \eval{$ mu^2/2x $}[0], \par \eval{$ Mg $}[M=70]. \end{verbatim} $\Longrightarrow$ \constants{ x=1,u=(10/36)U,m=5,g=10 }[U=50] \eval{$ mu^2/2x $}[0], \par \eval{$ Mg $}[M=70]. The force required to hold on to the baby is noticeably less than that required to lift a $70$~kg person – in fact about the same as that needed to lift a $50$~kg person. But we have ignored the force experienced by the mothers forearms – perhaps doubling $m$ (baby plus forearms) would give a better estimate of the force she experiences. In that case $mu^{2}/2x$ obviously doubles and the total force required by the woman to retain her baby – now $964$ newtons – is significantly more than that required to lift a $70$~kg person. I think it almost certain that the baby is torn from her arms. What difference does increasing the speed to 60 km/hr make? \begin{verbatim} \constants{ x=1,u=(10/36)U,m=5,g=10 }[U=60] \eval{$ mu^2/2x $}[1], \par \eval{$ Mg $}[M=70]. \end{verbatim} $\Longrightarrow$ \constants{ x=1,u=(10/36)U,m=5,g=10 }[U=60] \eval{$ mu^2/2x $}[0], \par \eval{$ Mg $}[M=70]. Now the force of baby alone is comparable to that required to lift a $70$ kg person. Including the woman's forearms in $m$, doubling $m$ say, will result in a force twice as great – like that required to lift two $70$~kg people or one $140$~kg person. There is no chance of the woman holding on to her baby. The force is too great. \subsubsection{Example 3: macros and constants} Constants can depend on previously defined and registered user macros. Suppose I have defined two macros \begin{verbatim} \NewDocumentCommand\electronmassprecisevalue {} {9.1093837015\times10^{-31}} \NewDocumentCommand\protonmassprecisevalue {} {1.672621898\times10^{-27}} \end{verbatim} (I have taken both the names and the values from the \verb`mandi` package.) The long explicit names of the macros has a pedagogic purpose, but they are too cumbersome to use in calculations. For that purpose we need, first, a \verb`\macros` statement registering the two macros with \texttt{numerica}, and then a \verb`\constants` statement like \begin{verbatim} \nmcConstants{ m_e=\electronmassprecisevalue, m_p=\protonmassprecisevalue } \end{verbatim} With that \verb`m_e` and \verb`m_p` could be entered in formulas, taking the values contained in the macros. Let's do it: \begin{verbatim} \NewDocumentCommand\electronmassprecisevalue {} {9.1093837015\times10^{-31}} \NewDocumentCommand\protonmassprecisevalue {} {1.672621898\times10^{-27}} \nmcMacros{ \electronmassprecisevalue, \protonmassprecisevalue } \nmcConstants{ m_e=\electronmassprecisevalue, m_p=\protonmassprecisevalue } \eval{$ m_p/m_e $} \end{verbatim} $\Longrightarrow$ \NewDocumentCommand\electronmassprecisevalue {} {9.1093837015\times10^{-31}} \NewDocumentCommand\protonmassprecisevalue {} {1.672621898\times10^{-27}} \nmcMacros{ \electronmassprecisevalue, \protonmassprecisevalue } \nmcConstants{ m_e=\electronmassprecisevalue, m_p=\protonmassprecisevalue } \eval{$ m_p/m_e $}, \noindent the familiar mass ratio of proton and electron. \subsection{Viewing, counting constants} To see all constants currently `in play', use the \verb`view` setting in the \verb`\constants` command. The main argument can be empty, \begin{centred} \verb`\constants[view]{}` $\Longrightarrow$ \constants[view]{} \end{centred} or contain a list of constants. In the latter case, the display is of the above form but featuring the constants of the new list or, if the \verb`add` setting is used, featuring the joined lists, old and new: \begin{centred} \verb`\constants[view,add]{X=42}` $\Longrightarrow$ \constants[view,add]{X=42} \end{centred} To count how many constants are currently in play, star the \verb`\constants` command. The number will depend on whether the main argument is empty or not, and whether the \verb`add` setting is active: \begin{centred} \verb`\constants*{}` $\Longrightarrow$ \constants*{}. \end{centred} If the \verb`view` setting is being used at the same time as the star, the \verb`view` prevails. \subsection{Errors} When contemplating error messages from \texttt{numerica} it needs to be remembered that \emph{multi-token} constants are added to the vv-list for every calculation. Hence an error may not be in the vv-list as indicated in the message but in the \verb`\constants` statement, specifically, the multi-token constants. \section{Saving and reusing results: \texttt{\textbackslash nmcReuse}} \label{sec:supplReuse}You may want to use at some place in a document a result calculated earlier. It would be good to be able to do so without having to do the calculation again at the new location. \texttt{numerica} offers a command \verb`\nmcReuse` (short-name form, \verb`\reuse`) which saves the numerical result of the most recent \verb`\eval`-uation to a control sequence (a macro) that can then be used elsewhere in the document, expanding to the saved result. The control sequence and its content are also saved to file, allowing the possibility of using the result in other documents. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% For those familiar with earlier usage, in version 2 of \texttt{numerica }the \verb`\nmcReuse` command was completely rewritten and was no longer compatible with how the command was used in version 1. In version 3 of \texttt{numerica} the command has, again, been reworked with an eye to greater consistency in its use (and simplifying the code). The command created difficulties for itself by mixing two functions: (i) saving and retrieving a result, and (ii) making the retrieved result usable within another calculation (an \verb`\eval`-uation). That latter function is the purpose of the \verb`\macros` command and in version 3 of \texttt{numerica} has been removed from \verb`\recur`. For a saved result to be used within an \verb`\eval` command it must first be `registered' by means of the \verb`\macros` command – like any other \LaTeX{} macro. Further, \emph{only the numerical result} is now saved, although that can be saved as a decimal or in scientific notation or fraction form, but saving associated elements like the vv-list or math delimiters with the numerical result has been discontinued.\end{shaded}% \end{minipage} \subsection{Use of \texttt{\textbackslash nmcReuse}} As noted, all the supplementary commands share the syntax of the \verb`\eval` command, so that \verb`\nmcReuse` has an optional settings argument preceding a mandatory main argument, followed by two trailing optional arguments. \verb`\nmcReuse` does not use the last two. The command is used to save the numerical result of the last \verb`\eval` command to file and to load saved results from file. The results are saved as pairs, \verb`\foo {}`, where \verb`foo` is a control sequence name (or macro name) chosen by the user. When loaded from file, \verb`\foo` is globally defined to expand to \verb``. The file that is used to store control sequences and their values is named \verb`<\jobname>.nmc` where \verb`\jobname` is the \LaTeX{} macro that expands to the filename of the current document. The file is organized as a comma list. Because of past practice, \begin{itemize} \item \verb`\nmcReuse{}`, or \verb`\reuse{}`, loads all saved macros and globally defines them to expand to their saved values; \item \verb`\nmcReuse{foo}`, or \verb`\reuse{foo}`, saves the numerical result from the most recent \verb`\eval`-uation to file in the form \verb`\foo {}` and globally defines \verb`\foo` to expand to \verb``. \end{itemize} In light of the first of these you may want to put \verb`\reuse{}` in the preamble of your document (\emph{after} \verb`\usepackage{numerica}` of course). In that way, saved control sequences are available from the start. But these are somewhat inconsistent default behaviours. Version 3 of \texttt{numerica} offers options to make more explicit what is being done: \begin{itemize} \item \verb`save` \begin{itemize} \item \verb`\reuse[save]{foo}` saves the numerical result from the latest \verb`\eval` command to file \verb`<\jobname>.nmc` as the pair \verb`\foo {}`;\verb`\foo` is globally defined to expand to \verb``; if \verb`\foo` is defined elsewhere in \LaTeX{} or already exists in \verb`<\jobname>.nmc` with a \emph{different} value then the save fails and a message is generated; \item \verb`\reuse[save]{}` is equivalent to \verb`\reuse{}`, see above; \end{itemize} \item \verb`renew` \begin{itemize} \item \verb`\reuse[renew]{foo}` saves the numerical result from the latest \verb`\eval` command to file \verb`<\jobname>.nmc` as the pair \verb`\foo {}`, if necessary overwriting any previously saved value for \verb`\foo`; \verb`\foo` is globally defined to expand to \verb``; if \verb`\foo` already exists elsewhere in \LaTeX{} then the save fails and a message is generated; \item \verb`\reuse[renew]{}` is equivalent to \verb`\reuse{}`, see above; \end{itemize} \item \verb`load` \begin{itemize} \item \verb`\reuse[load]{foo}` loads \verb`\foo` from file \verb`<\jobname>.nmc` and defines it globally to expand to its saved value; if \verb`\foo` is defined elsewhere in \LaTeX{} or if it does not exist in file \verb`<\jobname>.nmc` nothing happens; \item \verb`\reuse[load]{}` is equivalent to \verb`\reuse{}`, see above; \end{itemize} \item \verb`delete` \begin{itemize} \item \verb`\reuse[delete]{foo}` undefines \verb`\foo` in the current \LaTeX{} session and deletes \verb`\foo` and its value from file \verb`<\jobname>.nmc` should it be there; \item \verb`\reuse[delete]{}` deletes all contents from the file \verb`<\jobname>.nmc` and undefines all macros previously saved there from the current \LaTeX{} session; \end{itemize} \end{itemize} Only one of the options should be used at a time; if more than one is, it is the rightmost (in the settings option of the \verb`\reuse` command) which prevails. As examples of use, the following illustrate first the default behaviour and then the explicit use of the \verb`save` option. \begin{verbatim} \eval{$ x+y $}[x=-1,y=3] \par \reuse{two} >> \two \ << \end{verbatim} $\Longrightarrow$ \eval{$ x+y $}[x=-1,y=3] \par \reuse{two} >> \two \ << \noindent Only the numerical result is saved, not the math environment, so that if you want a minus sign to display correctly (rather than as a hyphen) when you use a saved control sequence you will need to ensure it is used in a math environment: \begin{verbatim} \eval{$ -1-1 $}. \reuse[save]{negtwo} Now use the control sequence: $\negtwo$. \end{verbatim} $\Longrightarrow$ \eval{$ -1-1 $}.\reuse{negtwo} Now use the control sequence: $\negtwo$. There may be occasions when you wish to change a previously saved value and yet, irritatingly, the control sequence name will now be known to \LaTeX{} and so will generate an `already defined' message. And if you choose a different name for the control sequence to save the new value to, do you want the old name cluttering the \verb`.nmc` file? The settings \verb`delete` and \verb`renew` provide for such situations. The following example shows the use of these options. In the example a control sequence \verb`\testing` is defined in the first line. Being unable to recall what is in the \verb`.nmc` file, I try deleting it from there in the second line. In the third line the sum of the first ten integers is evaluated. In the fourth line I try to save the sum to the control sequence \verb`\testing`. That generates a message: \verb`\testing` is defined elsewhere (in \LaTeX ) and therefore was \emph{not} deleted. Okay, I resort to a new control sequence \verb`\test`. In the fifth line, in case it is present in the \texttt{.nmc} file, I try deleting \verb`\test` from there. The lack of a message means that either it was successfully deleted or was not present in the \texttt{.nmc} file in the first place. In the following lines, I calculate the sum of the first 20 integers and save the result to \verb`\test`. The final line shows that this was successful. \begin{verbatim} \NewDocumentCommand\testing{}{1} \reuse[delete]{testing} \eval[env=\[ ]{\sum_{n=1}^{10}n} \reuse{testing}\par \reuse[delete]{test}\par \eval[env=\[ ]{\sum_{n=1}^{20}n} \reuse{test} Now testing \textbackslash test: \test. \end{verbatim} $\Longrightarrow$ \NewDocumentCommand\testing{}{1} \reuse[delete]{testing} \eval[env=\[ ]{\sum_{n=1}^{10}n} \reuse{testing}\par \reuse[delete]{test}\par \eval[env=\[ ]{\sum_{n=1}^{20}n} \reuse[renew]{ test} Now testing \textbackslash test: \test. If a control sequence \verb`\foo` is already known to \LaTeX{} from elsewhere (perhaps it is a \LaTeX{} command) then writing \verb`\reuse{foo}` or \verb`\reuse[save]{foo}` or even \verb`\reuse[renew]{foo}` will produce a message and the result of the latest \verb`\eval`-uation will \emph{not} be saved : \begin{verbatim} \eval*{\sum_{n=1}^{10}n}\par \reuse[renew]{sigma} \par >> $\sigma$ << \end{verbatim} $\Longrightarrow$ \eval*{\sum_{n=1}^{10}n} \par \reuse[renew]{sigma}\par >> $\sigma$ << \noindent As you can see, \verb`\sigma` is unchanged. If a control sequence is already saved to file from a previous \verb`\reuse` command trying to save a different value to it produces a message: \begin{verbatim} \eval{$-1-1-1$} \par \reuse{negtwo} \end{verbatim} $\Longrightarrow$ \eval{$-1-1-1$} \par \reuse{negtwo}\medskip{} \noindent If you really do want to change the stored value, use the \verb`renew` option. Empty results (from an \verb`\eval`-uation) are \emph{not} saved. A following \verb`\reuse` command which attempts to do so generates another message: \begin{verbatim} \eval{1/0} \par \reuse{oops} \end{verbatim} $\Longrightarrow$ \reuse[delete]{oops}\eval{1/0}\par\reuse{oops}\medskip{} \noindent The \verb`\eval`-uative error has produced an error message and an empty result which generates the \verb`\reuse` message.\emph{ }However, if \verb`\oops` had already existed in \verb`<\jobname>.nmc` the stored macro and its value would have been loaded to prevent \LaTeX{} later complaining about an undefined control sequence, should \verb`\oops` have been used later in the document, and halting compilation. \subsubsection{Seeing what is saved} The \verb`view` setting is available for \verb`\reuse`, as for other commands. \begin{itemize} \item \verb`\reuse[view]{}` displays all saved commands and their values; \item \verb`\reuse[view]{foo}` displays only \verb`\foo` and its contents. \end{itemize} \verb`view` is independent of the other \verb`\reuse` options and can be used freely with them: they do their thing, and \verb`view` shows what results. For instance, the option combination \verb`[view,delete]` results \emph{first} in the deletion and only after in the viewing. Note that because \verb`\reuse{foo}` is equivalent to \verb`\reuse[save]{foo}`, so \verb`\reuse[view]{foo}` is equivalent to \verb`\reuse[save,view]{foo}`. \subsubsection{Saving in other number formats} \label{subsec:reuseOtherFormats}\texttt{numerica} can output numbers in scientific notation and in fraction form and save them in that form. In the example, to check that both results have indeed been saved, I use the \verb`view` option: \begin{verbatim} \eval{ \pi }[//t6], \reuse[renew]{fracpi} \quad \eval{ \pi }[xx]. \reuse[renew]{scipi} \reuse[view]{} \end{verbatim} $\Longrightarrow$ \eval{ \pi }[//t6], \reuse[renew]{fracpi} \quad \eval{ \pi }[xx]. \reuse[renew,view]{scipi} \subsection{Using saved macros in calculations} To use a saved value in an \verb`\eval`-uation requires first `registering' the control sequence (the macro) containing the value with \texttt{numerica}. This is hardly surprising: saved control sequences are macros and \texttt{numerica} needs to be alerted to their presence as with other macros. The macros \verb`\two` and \verb`\negtwo` are active in the current document but, in the following example, the initial attempt to use them in an \verb`\eval` command fails; the second time, after registering with the \verb`\macros` command, it succeeds: \begin{verbatim} \eval{ \two \times \negtwo }\par \macros{ \two, \negtwo } \eval{ \two \times \negtwo } \end{verbatim} $\Longrightarrow$ \eval{ \two \times \negtwo }\par \macros{ \two, \negtwo } \eval{$ \two \times \negtwo $} \subsection{The \texttt{.nmc} file} \label{subsec:suppleReuse.nmc-file}The file that control sequences are saved to has a filename composed of the document name with the extension \texttt{.nmc}. If your document is \texttt{mydoc.tex} (so that the \LaTeX{} command {\small\verb`\jobname`} expands to \texttt{mydoc}) then the file to which results are saved is \texttt{mydoc.nmc}, located in the document directory. The \texttt{.nmc} file is a comma list of pairs of the form \verb`\csname {value}`. Thus, the contents of \verb`mydoc.nmc` might be \verb`\csname1` {\ttfamily\verb`{value1}`},\verb`\csname2` {\ttfamily\verb`{value2}`},..., \verb`\csname-n` \verb`{value-n}`. If \texttt{mydoc.nmc} does not already exist then \verb`\reuse{csname}` will create it in the document directory, and \verb`\csname {value}` will becomes its first element. \subsubsection{Editing the \texttt{.nmc} file externally} \label{subsec:supplEditing-the-.nmc}The \texttt{.nmc} file is a text file and can be edited in a text editor. Thus it is possible to externally add control sequences and values to it provided the (simple) structure of the file is strictly adhered to: pairs like \verb`\csname {value}` separated by commas. It is also possible to delete items from it or rename control sequences or edit values by the same mechanism. Editing the file externally like this, or renaming it, or transferring items from one \texttt{.nmc} file to another, provides a way of using saved values in multiple documents. \subsection{Counting, viewing all saved control sequences} The \verb`\reuse` command has a starred form, \verb`\reuse*` (or \verb`\nmcReuse*`) which, like other starred commands, produces a purely numerical result. The number is the count of how many control sequences have been saved: \begin{centred} \verb`\reuse*{}` $\Longrightarrow$ \reuse*{ } \end{centred} The star does not interfere with the other functions of \verb`\reuse`; the main argument does not need to be empty. \subsection{Obsolete \texttt{reuse} setting of \texttt{\textbackslash eval} command} \noindent\label{subsec:supplReuseEvalSetting}In version 2 of \texttt{numerica }the \verb`\eval` command had a setting \verb`reuse` that gave some choice as to what was saved. That has been discontinued. \texttt{numerica} evaluates mathematical expressions; the numerical result is what is important; the rest is cosmetics. Adding the extra capability was confusing both as to what was saved and where and how it could be used – and complicated the code. For the added complexity there was little gain. \chapter{Miscellaneous matters} In this chapter I consider the nesting of commands, the parsing of mathematical arguments, the use of different mathematical environments and the use of \texttt{numerica} in the document processor \LyX . \section{Nesting commands} \label{sec:miscNesting} The \verb`\eval` command and the supplementary commands of the previous chapter can be \emph{nested} –\emph{ }used within other \verb`\eval` or supplementary commands. Nesting may occur in the main argument, or the vv-list, or the settings option, or some combination of all three. With the commands currently introduced, nesting is unlikely to be a major concern, but it becomes significant for the commands defined in the associated package \texttt{numerica-plus} (see §\ref{subsec:introPackagesOptions}). Since those additional commands are not available for this document, the examples below use the commands introduced earlier: \verb`\eval`, \verb`\info`, \verb`\macros`, \verb`\constants` and \verb`\reuse`. \subsection{In the formula} Consider a statement like \verb`\eval{...\eval...}`. There is an inner \verb`\eval` and an outer \verb`\eval`. The inner \verb`\eval` `digests' \emph{its} \LaTeX{} formula to produce an \texttt{l3fp}-readable expression which is fed to \texttt{l3fp} to evaluate. The result is then fed to the outer \verb`\eval` to be inserted into the outer formula to be evaluated and then displayed. In version 1 of \texttt{numerica} that meant the inner command \emph{had} to be starred, \verb`\eval*`, so that no display formatting was fed to the outer command to try to digest (and cause an error).\emph{ }From version 2 of \texttt{numerica} this is no longer the case. \texttt{numerica} detects whether a command is inner or outer, and if inner, suppresses all display formatting, producing only a number, as if the command had been starred: \begin{centred} \verb`\eval{$ \sin(\eval{\sin x}[x=\pi/6]\pi) + 1 $}` $\Longrightarrow$ \eval{ $\sin(\eval{\sin x}[x=\pi/6]\pi) + 1 $}. \end{centred} In the presentation of the overall result, the inner \verb`\eval` command is evaluated, displaying as a number. In the example, the inner vv-list could be attached to the outer \verb`\eval` \verb`x=\pi/6` since outer variables are available to the inner command – and it aids clarity: \begin{centred} \verb`\eval{$ \sin(\eval{\sin x}\pi) + 1 $}[x=\pi/6]` $\Longrightarrow$ \eval{$ \sin(\eval{\sin x}\pi)+ 1$}[x=\pi/6]. \end{centred} Or both inner and outer commands could have their own vv-lists – indeed, the same variable could appear in both and be assigned different values in each, without conflict: \begin{centred} \verb`\eval{$ \sin(\eval{\sin x}[x=\pi/6]\pi) + x $}[x=1]` $\Longrightarrow$ \eval{$ \sin(\eval{\sin x}[x=\pi/6]\pi) + x $}[x=1]. \end{centred} Just to show that it is possible, the next example shows \verb`\eval` being used in a \verb`\constants` command. The \verb`o` setting in the \verb`\constants` command pervades its argument; hence it needs to be explicitly turned off for the \verb`\eval` if \verb`\sin(\pi/6)` is to evaluate as expected. \begin{verbatim} \constants[o]{ y=\sin 30, x=\eval[o=0]{\sin(\pi/6)} } \eval{$ x+y $} \end{verbatim} $\Longrightarrow$ \constants[o]{ y=\sin 30, x=\eval[o=0]{\sin(\pi/6)}} \eval{$ x+y $}. \subsubsection{Math delimiters and double evaluations} Any math delimiters in the inner \verb`\eval` are ignored. (This also differs from version 1 of \texttt{numerica} where they caused an error.) Obviously it is simpler to omit them as I have done in the examples. However, math delimiters in the outer \verb`\eval` command still have their normal effect and produce a \emph{formula = result, (vv-list)} display. One consequence of such a display is that the formula in the inner \verb`\eval` command is evaluated \emph{twice} – once when the overall result is being calculated (i.e.\ the formula of the outer \verb`\eval`) and later when the overall display of the result is created. In the \emph{formula} part of the \emph{formula = result, {[}vv-list{]}} display, the tokens in the \emph{formula} are expanded to their display form. For example, \verb`\sin` is expanded to $\sin$, \verb`\pi` is expanded to $\pi$ – and the inner \verb`\eval` is expanded to the numerical result of its evaluation – which means a second evaluation. If the inner formula is simple, this will be of little moment, but should the inner formula contain, say, a slowly converging infinite series, then evaluating it twice is a bad idea and it would be better to remove the delimiters from the outer \verb`\eval`. That prevents the second evaluation. The problem does not arise if the outer \verb`\eval` lies within a math environment (e.g.\ \verb`$ \eval{...} $`) since that produces a display of the form \emph{result, (vv-list).} The formula is not displayed and so the second evaluation does not occur. The inner \verb`\eval` is evaluated once only to calculate the result. \subsection{In the vv-list} The inner \verb`\eval` can be placed in the vv-list of the outer command. If the vv-list of the inner \verb`\eval` contains a comma then the entire inner \verb`\eval` and its \LaTeX{} arguments needs to be wrapped in braces to hide \emph{its} comma from the vv-list of the outer \verb`\eval`. To show the effect of not doing so, I have slightly complicated a previous example by adding a second (unnecessary) variable. The first example is with braces, the second without: \begin{centred} \verb`\eval{$ \sin k\pi + 1 $}[k={\eval{y\sin x}[x=\pi/6,y=1]}]` $\Longrightarrow$ \eval{$ \sin k\pi + 1 $} [k={\eval{y\sin x}[x=\pi/6,y=1]}]. \verb`\eval{$ \sin k\pi + 1 $}[k=\eval{y\sin x}[x=\pi/6,y=1]]` $\Longrightarrow$ \eval{$ \sin k\pi +1 $}[k=\eval{y\sin x}[x=\pi/6,y=1]]. \end{centred} The vv-list of the outer \verb`\eval` is parsed as containing two entries, first \verb`k=\eval` \verb`{y\sin x}[x=\pi/6` and second \verb`y=1]` (containing the right bracket). Both will cause errors but since the vv-list is evaluated from the right, it is \verb`y=1]` which actually does so. \subsection{In the settings option} This will be rare, but commands can occur in the settings option of the outer command. The \verb`\info` command provides a good example. I have included it in the punctuation setting of an \verb`\eval`-uation. \begin{verbatim} \eval[p=\mbox{,\qquad\info{sum} terms.}] {\[ \sum_{n=0}^{\infty}\frac{(-1)^{n}}{n!} \]}[3] \end{verbatim} $\Longrightarrow$ \eval[p=\mbox{,\qquad\info{sum} terms.}]{\[ \sum_{n=0}^{\infty}\frac{(-1)^{n}}{n!}\]}[3] Because of the \verb`\[ \]` math delimiters, if the \verb`\info` command had been placed \emph{after} the \texttt{\textbackslash eval} command, it would have slid down to the next line. Used in the settings, as here, the display is \emph{inside} the \verb`\[ \]` delimiters, on the same line as the expression. This may be significant for adjusting vertical spacing of later parts of the document – widow and orphan control for instance. A point to note is the explicit writing of the `terms' descriptor. Normally \verb`\info{sum}` would automatically supply the descriptor, but as noted earlier, nesting of one command in another suppresses all elements of display of the inner command beyond the numerical result. It is as if the inner command is starred. Because the \verb`\info` command is nested in the \verb`\eval` command, the `terms' descriptor is suppressed and has had to be explicitly supplied by hand. \subsection{Rounding and display} In the display of the overall result, it is the numerical outcome of the inner command which is shown, not the formula that the inner command acts on. In previous versions of \texttt{numerica} that result was \emph{always} evaluated to $16$ figures which were then fed into the formula of the outer command. From version 3.0.0, the number-format option of the inner command is heeded, \emph{if it is present}, and only the specified number of decimal digits of the floating point result are fed to the the outer command. In its absence, the inner command feeds $16$ significant figures to the the outer command. For example, \begin{verbatim} \eval[env=alignat*,ff]{ \pi - \eval{ \pi }, \pi - \eval{ \pi }[4] }[15*] \end{verbatim} $\Longrightarrow$ \eval[env=alignat*,ff]{ \pi - \eval{ \pi }, \pi - \eval{ \pi }[4] }[15*] \noindent In the first instance, with no explicit number-format specification for the inner \verb`\eval`, the outer result is zero because all $16$ significant figures of the inner result have been passed to the outer \verb`\eval`; in the second instance, with an explicit rounding number specified, only $4$ decimal digits have been passed to the outer \verb`\eval` and as a consequence the overall result does not vanish. \subsubsection{\textquoteleft\texttt{-ed}\textquoteright{} environments} With `inner' environments like \verb`cases` and \verb`dcases`, \verb`array` and the AMS `\verb`-ed`' environments which are used \emph{within} a math environment, there can be a conflict between display and result when commands are nested. Consider the example \begin{verbatim} \[ \eval[env=array,pp,p=.,ff]{ \pi - \eval{ \pi }, \pi - \eval{ \pi }[15] }[15*] \] \end{verbatim} $\Longrightarrow$ \[ \eval[env=array,pp,p=.,ff]{\pi - \eval{ \pi }, \pi - \eval{ \pi }[15] }[15*] \]In both instances the result is zero to all $16$ significant figures, but only the second instance, where an explicit rounding number is specified, displays correctly. The \emph{implicit} rounding number in the first instance is used in the display but not in the calculation. To see what is going on in this case, put \verb`dbg=7*11` in the settings option. This will display both the fp-form and the \LaTeX{} form of the result: \begin{verbatim} \[ \eval[env=array,dbg=7*11]{ \pi - \eval{ \pi } }[15*] \] \end{verbatim} $\Longrightarrow$ \[ \eval[env=array,dbg=7*11]{ \pi - \eval{ \pi } }[15*] \] \noindent In the \emph{formula} part of the \emph{formula=result} display, the \emph{formula} contains the unevaluated \verb`\eval{ \pi }`, whereas the \emph{result} has long since been evaluated. When \LaTeX{} comes to display the whole thing, the \verb`\eval` in the \emph{formula }is finally expanded, which means evaluated. The rounding value is the implicitly specified $6$ decimal places of \emph{this} \verb`\eval`, not the explicitly specified $15$ of the outer \verb`\eval`. This is a problem for this group of `inner' environments. The solution is to explicitly specify rounding numbers for inner \verb`\eval` commands. \subsection{Error messages} Errors in an inner command create a small change in error message display. \begin{centred} \verb`\eval{ 1 + \eval{ 1 + \eval{ k } } }` $\Longrightarrow$\\ \eval{ 1 + \eval{ 1 + \eval{ k } } } \verb`\eval{ x + \eval{ k }[k=\arcsin 2] }[x=1]` $\Longrightarrow$\\ \eval{ x + \eval{ k }[k=\arcsin 2] }[x=1] \end{centred} An integer is added to the `where' part of the error message. The integer indicates the \emph{depth} (or \emph{level}) where the error occurs. For an error at the top level the integer is suppressed, even though there may be nesting elsewhere in the overall expression. This is in the interests of straightforwardness when nesting is absent, which will be overwhelmingly the most common situation. \begin{centred} \verb`\eval{ k + \eval{ x }[x=1] }[k=\arcsin 2]` $\Longrightarrow$\\ \eval{ k + \eval{ x }[x=1] }[k=\arcsin 2] \end{centred} \subsection{Debugging} \label{subsec:miscNestingDebugging}It is worth looking at the debug display when \verb`\eval` commands are nested. For the outer \verb`\eval` command: \begin{centred} \verb`\eval[dbg=1]{$ \sin \eval{\sin x}[x=\pi/6]\pi + 1 $}` $\Longrightarrow$ \eval[dbg=210]{$ \sin \eval{\sin x}[x=\pi/6]\pi + 1$} \end{centred} There is no vv-list for the outer command whence the two empty slots in the display but when the inner \verb`\eval` is in the vv-list, they are filled: \begin{centred} \verb`\eval[dbg=1]{$ \sin k\pi + 1 $}[k={\eval{\sin x}[x=\pi/6]}]` $\Longrightarrow$ \eval[dbg=1]{$ \sin k\pi + 1$} [k={\eval{\sin x}[x=\pi/6]}] \end{centred} Contrary to their behaviour (which was accidental) in earlier versions of \texttt{numerica} debug numbers have no effect when used with an inner \verb`\eval` command: \begin{verbatim} \eval{$ \sin{\left( \eval[dbg=1]{ \sin x }[x=\pi/6] \right)\pi} + 1 $} \end{verbatim} $\Longrightarrow$ \eval{$ \sin{\left( \eval[dbg=-1]{ \sin x }[x=\pi/6] \right)\pi} + 1 $} In the example, note the use of braces to define the argument of the outer \verb`\sin` function; see §§\ref{subsec:evalBraced-groups}, \ref{subsec:calcComplicated-arguments}. \section{Parsing mathematical arguments} \label{sec:miscArgument-parsing} A main aim of the \texttt{numerica} package is to require minimal, preferably no, adjustment to the \LaTeX{} form in which an expression is typeset in order to evaluate it. But when writing formulas mathematicians do not follow codified rules of the kind programming languages insist on – like parenthesizing the arguments of functions, or inserting explicit multiplication signs ({*}) between juxtaposed terms. For the package to attain its aim, the question of where the arguments of mathematical functions end is acute. Before discussing the rules \texttt{numerica} uses to answer this question, I discuss the tools the package provides to handle exceptions to those rules, when an author \emph{does} need to make some adjustment to a formula for it to be evaluated correctly. \subsection{\protect\LaTeX{} braces} \label{subsec:settingsBraces}So, one has a complicated argument to a mathematical function. It is clear to a person reading the compiled expression in the \texttt{pdf} where the argument ends. The simplest way to make it clear to \texttt{numerica} also is by enclosing the argument in \LaTeX{} braces. This is the recommended practice from version 3.0.0 of \texttt{numerica}, both because braces do not alter the visual appearance of the formula in the \texttt{pdf} and because it is consonant with general \LaTeX{} practice. The following expression, $\sin(n+\tfrac{1}{2})(x-t)$, or one like it, occurs in multiple texts on Fourier series. The human reader understands that the argument of the sine includes \emph{both} parenthesized factors. But asking \texttt{numerica} to evaluate it `as is' produces \begin{centred} \verb`\eval{$ \sin(n+\tfrac12)(x-t) $}[n=3,x=t+\pi,t=1.234]` $\Longrightarrow$ \eval{$ \sin(n+\tfrac12)(x-t) $}[n=3,x=t+\pi,t=1.234], \end{centred} which is $(\sin\tfrac{7}{2})\times\pi$ and not what was intended. Enclosing the whole argument – both factors – in braces rescues the situation, \begin{centred} \verb`\eval{$ \sin{(n+\tfrac12)(x-t)} $}[n=3,x=t+\pi,t=1.234]` $\Longrightarrow$ \eval{$ \sin{(n+\tfrac12)(x-t)} $}[n=3,x=t+\pi,t=1.234], \end{centred} which is $\sin(\tfrac{7}{2}\pi)$, as intended. Another example is \begin{centred} \verb`\eval{\[\cos{\frac{2\pi}T n(t+\tfrac12T)}\]}[T=2,t=1,n=3]` $\Longrightarrow$ \eval{\[ \cos{\frac{2\pi}{T}n(t+\tfrac12T)} \]}[T=2,t=1,n=3] \end{centred} which otherwise evaluates to $-6$. See §\ref{subsec:calcComplicated-arguments} for further examples. The point is that the braces do not alter the visual appearance in the \texttt{pdf} but do delimit the whole argument for the \verb`\eval` command. \subsection{The cleave commands \texttt{\textbackslash q} and \texttt{\textbackslash Q}} \label{subsec:miscCleave}An alternative to using braces is to use \texttt{numerica}'s `cleave' commands. The word \emph{cleave} has two opposed meanings: to adhere or cling to, and to split apart or separate. \texttt{numerica} defines two commands, \verb`\q` and \verb`\Q` to achieve these opposite effects. When a mathematical argument is being parsed, the \verb`\q` command joins the next token to the argument (cleaves\emph{ to}); the \verb`\Q` command severs the next token from the argument (cleaves\emph{ apart}). Neither command leaves a visible trace in the output or has any other effect on the calculation beyond joining or severing the tokens on either side. Repeating the penultimate example with \verb`\q` between the bracketed factors rather than enclosing all in braces, \begin{centred} \verb`\eval{$ \sin(n+\tfrac12)\q(x-t) $}[n=3,x=t+\pi,t=1.234]` $\Longrightarrow$ \eval{$ \sin(n+\tfrac12)\q(x-t) $}[n=3,x=t+\pi,t=1.234]. \end{centred} which again is $\sin(\tfrac{7}{2}\pi)$. The \verb`\Q` command splits an argument. Without it, we have \begin{centred} \verb`\eval{$ \ln n\,X $}[n=2,X=e^2]` $\Longrightarrow$ \eval{$ \ln n\,X $}[n=2,X=e^2]; \end{centred} with \verb`\Q` inserted before the fraction, \begin{centred} \verb`\eval{$ \ln n\Q\,X $}[n=2,X=e^2]` $\Longrightarrow$ \eval{$ \ln n\Q\,X $}[n=2,X=e^2]. \end{centred} However, an author could be kinder to the reader by not using a thin space (\verb`\,`) to indicate separation of the terms but rather parentheses, ($(\ln n)X$, or rearrangement, $X\ln n$, and avoid the need for \verb`\Q` entirely. \subsubsection{Mnemonic} As mnemonic, best seen in sans serif for the Latin Modern fonts used in this document, think of the letter \textsf{q} as a circle cleaving\emph{ to} a vertical descender; think of the letter \textsf{Q} as a circle cleaved\emph{ asunder} by the diagonal stroke. \subsection{Parsing groups} A formula is a sequence of tokens and brace groups. When evaluating a formula, \verb`\eval` digests the formula from the left, \LaTeX{} argument by \LaTeX{} argument, where \emph{argument} here means either a token (an N-type argument in \verb`expl3`-speak) or a brace group (an n-type argument). Some mathematical functions have arguments which correspond to \LaTeX{} arguments – think \verb`\sqrt`, \verb`\frac`, \verb`\binom`; also \verb`^`. But for mathematical functions like \verb`\surd` or \verb`\sin` or \verb`\ln`, this is not so; nor is it for sums and products, nor for comparisons. There need be no direct translation of \LaTeX{} argument (an `L-arg') to mathematical argument (an `M-arg'). \begin{wraptable}{o}{0.5\columnwidth}% \caption{ Parsing groups}\label{tab:miscShadingGroups} \begin{centering} \begin{center} \begin{tabular}{ll} \toprule group & function/operation\tabularnewline \midrule I & surd, \verb`Not`\tabularnewline II & unary functions, \verb`/`\tabularnewline III & sums, products\tabularnewline IV & comparisons\tabularnewline V & \verb`And`, \verb`Or`\tabularnewline \bottomrule \end{tabular} \par\end{center} \par\end{centering} \end{wraptable}% Different mathematical functions, operations, relations – for convenience call them collectively \emph{functions} – have different reaches when it comes to how we read subsequent tokens. We might think of a function as casting a shadow over subsequent tokens; what lies in the shadow is part of its argument; what lies beyond the shadow is not. Table §\ref{tab:miscShadingGroups} lists the different \emph{parsing groups }(alternatively \emph{shading groups}) that \texttt{numerica} takes account of. Those functions with the lowest group number have the shortest reach, cast the shortest shadows which progressively lengthen as the group number increases. To justify the groupings in Table~\ref{tab:miscShadingGroups}, I look at examples, particularly from \emph{HMF} but also from G. H. Hardy, \emph{A course of pure mathematics}, and other sources and use the following terminology. A mathematical argument may end \emph{at} an L-arg, meaning immediately before the L-arg, or end \emph{with} the L-arg, meaning immediately after the L-arg. Ending or not will in general depend on whether the argument is in \emph{first position} – the position immediately following a function token like \verb`\sin` or \verb`\surd` – or in \emph{general position} – any later position. Formatting elements do not change the position count. This applies to things like spaces or phantoms (and their arguments) or modifiers like \verb`\left` or \verb`\biggl`. Multi-token numbers (in decimal or scientific formats) are treated as single items; they advance the position count by exactly one. Finally, a \emph{naked} sign (like a plus or minus sign) is one that is \emph{not} enclosed in brackets lying wholly to the right of the function whose argument is being determined. \subsubsection{Parsing group I} The only functions in this category are the surd and logical \verb`Not`. Why distinguish the surd from other unary functions? Hardy writes (§13) $\surd(pq)$ but (§206) $\log xy=\log x+\log y$ – the surd does not have the reach of the logarithm. The logarithm extends to both members of a product; the surd does not and the factors need to be parenthesized if the surd is to apply to both.\emph{ }Surely we all agree that \verb`\sin2\pi`, displaying as $\sin2\pi$, vanishes? The argument of the sine extends beyond the $2$ to include the $\pi$. But \verb`\surd2\pi`, displaying as $\surd2\pi$, we understand to be $\surd2\times\pi$. The argument of the surd ends with the $2$. The surd binds more tightly to its argument than is true of unary functions generally. For parsing group I \begin{enumerate} \item if a left bracket is in first position, the mathematical argument ends with the matching right bracket; otherwise \item the argument ends with the item in first position and any L- or M-args required by that item. \end{enumerate} If the factorial sign \verb`!` \emph{preceded} its argument, it too would belong in this parsing group, for it also binds tightly like the surd. This means that an expression like $\surd4!$ is intrinsically ambiguous. Is it the square root of $24$ or the factorial of $2$? In \texttt{numerica} it produces the (perhaps rather odd) error \begin{centred} \verb`\eval{$ \surd 4! $}` $\Longrightarrow$ \eval{$ \surd4! $} \end{centred} Since \verb`\eval` digests a formula from the left, the surd seizes the argument \verb`4`; there is then nothing for the factorial to operate on. Parenthesizing like either \verb`(\surd 4)!` or \verb`\surd(4!)` repairs the situation. Because other unary functions (like the sine or logarithm) do not bind as tightly, this ambiguity does not arise for them. Exponents cause no problem because taking square roots and raising to a power are commutative operations – the result is the same whichever is performed first. \begin{centred} \verb`\eval[pp,ff]{$ \surd 3^4, \surd(3^4), (\surd3)^4 $}` $\Longrightarrow$ \eval[pp,ff]{$ \surd 3^4, \surd(3^4), (\surd3)^4 $}. \end{centred} \subsubsection{Parsing group II} This category includes the trigonometric and hyperbolic functions, their inverses, the various logarithms and the exponential functions, and the signum function \verb`\sgn`. It also includes the denominators of slash fractions \verb`/`. \begin{itemize} \item In parsing group II we wish to accommodate usages like $\ln z^{n}=n\ln z$ (\emph{HMF} 4.1.11), or $2\arctan e^{z}$ (\emph{HMF} 4.3.117), meaning an exponent is included in the argument. This must include exponents of parenthesized arguments to accommodate \[ \ln\left(1+\frac{x}{n}\right)^{n}=n\ln\left(1+\frac{x}{n}\right). \] \item An approximation to Stirling's formula for the factorial is often written $\ln N!\approx N\ln N-N$ (widely used in texts on statistical mechanics). Hence the factorial sign should also be considered part of the argument. \item $\ln xy=\ln x+\ln y$ means the argument must reach over a product of variables. Identities like $\sin2z=2\sin z\cos z$ mean the argument also reaches over numbers, and expressions like $\sin\tfrac{1}{2}\pi x$ (\emph{HMF} 4.3.104) mean that it further reaches over \verb`\tfrac`-s and constants. \item Essentially \emph{anything }can be in first position, and without parentheses; e.g. \begin{itemize} \item unary functions: $\ln\ln z$ (\emph{HMF} 4.1.52), $\ln\tan\dfrac{z}{2}$ (\emph{HMF} 4.3.116), \item fractions: $\ln\dfrac{z_{1}}{z_{2}}$ (\emph{HMF} 4.1.9), $\arcsin\dfrac{(2ax+b)}{(b^{2}-4ac)^{1/2}}$ (\emph{HMF} 3.3.36), $\ln\dfrac{\tan z}{z}$ (\emph{HMF} 4.3.73), \item absolute values: $\ln\abs*{\dfrac{a+x}{a-x}}$ (\emph{HMF} 3.3.25), \item square roots: $\arctan\sqrt{\dfrac{\nu_{1}}{\nu_{2}}F}$ (\emph{HMF }26.6.8) \end{itemize} \end{itemize} With these examples in mind, for parsing group II \begin{enumerate} \item if a left bracket is in first position, the mathematical argument ends with the matching right bracket and any attached exponent, or factorial or double factorial sign; otherwise \item the mathematical argument includes the item in first position and any L- or M-args required by that item; \begin{enumerate} \item if the item in first position is a number, variable, constant or \verb`\tfrac` \begin{enumerate} \item the argument appends the next item if it is a number, variable, constant or \verb`\tfrac`, and so on recursively; or \item the argument appends the next item if it is an exponent, or facorial or double factorial sign, and ends there; otherwise \item the argument ends. \end{enumerate} \item if the item in first position is not a number, variable, constant or \verb`\tfrac` \begin{enumerate} \item the argument appends the next item if it is an exponent, or factorial or double factorial sign, and ends there; otherwise \item the argument ends. \end{enumerate} \end{enumerate} \end{enumerate} Thus an argument may extend over numbers, constants, variables and \verb`\tfrac`-s, as instanced by $\sin2\tfrac{p}{q}\pi x$ which exhibits all elements. There are still areas of ambiguity. Consider the different outcomes here (the logarithms are to base $10$): \begin{centred} \verb`\eval[pp,ff]{$ \log m^3n, \log nm^3 $}[m=10,n=5]` $\Longrightarrow$ \eval[pp,ff]{$ \log m^3n, \log nm^3 $}[m=10,n=5]. \end{centred} In both instances the argument stops with the exponent, which means $n$ is \emph{not} part of the argument in the first. Any criterion is going to miss some instances where a different outcome might be anticipated. Where an argument ends is affected by visual appearance in the \texttt{pdf}. Anything that breaks the `visual flow' of juxtaposed numbers, variables, constants and \verb`\tfrac`-s is considered by \texttt{numerica} to end the argument. An exponent does that. If you feel ambiguity is possible, parenthesize or rearrange to clarify. Similarly, a \verb`\dfrac` breaks the visual flow in the following: \begin{centred} \verb`\eval[pp,ff]{$ \sin\dfrac12\pi, \sin\tfrac12\pi $}` $\Longrightarrow$ \eval[pp,ff]{$ \sin\dfrac12\pi, \sin\tfrac12\pi $}. \end{centred} Nearly always, someone writing an expression like this intends the $\pi$ to be part of the argument. In that case, a \verb`\tfrac` should be used since the \verb`\dfrac` breaks the `visual flow' of the argument. \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% \paragraph{\texttt{\textbackslash frac}} The problem comes with \verb`\frac` which in an inline environment displays like \verb`\tfrac`. I considered making the argument behaviour of \verb`\frac` the same as \verb`\tfrac` for textstyle contexts, and the same as \verb`\dfrac` for displaystyle contexts, but that would have meant the same expression evaluating to different results depending on whether it lay in an inline or displaystyle environment. That was unacceptable and for argument determination \verb`\frac` is treated like \verb`\dfrac` in \emph{all} environments.\end{shaded}% \end{minipage} \paragraph{Slash~fraction denominators} When using \verb`/` to write fractions or indicate division, it is easy to write ambiguous expressions. How should $\pi/2n$ be interpreted? With from-the-left evaluation and calculator precedence rules (which give equal precedence to multiplication and division), this would be interpreted as $(\pi/2)\times n$, but most people will instinctively interpret it as $\pi/(2n)$ and this is what \texttt{numerica} does. It places \verb`/` in parsing group II and treats the denominator of the slash \emph{as if it were the argument of a unary function}. This means that $1/2\sin(\pi/6)$ is parsed as $(1/2)\sin x$ rather than as $1/(2\sin x)$. It also means that $1/2\exp(1)$ and $1/2e$ give different results. In the author's view this is acceptable since they display differently and are not instinctively read in the same way. (But again authors should paranthesize or rearrange to avoid ambiguity.) \paragraph{Trigonometric functions} \label{subsec:miscTrigFns}Trigonometric functions are set to parsing group II. This accommodates many instances of how arguments are used with these functions, but trigonometrical identities and Fourier series in particular make a nonsense of the restrictions. I find $\tan\tfrac{1}{2}(A+B)$ (\emph{HMF }4.3.148) and $\sec\pi(\tfrac{1}{4}+\tfrac{1}{2}az)$ (\emph{HMF }19.3.3), $\cos(2m+p)z$ (\emph{HMF }20.2.3) and $\sin(2n+1)v$ (\emph{HMF }16.38.1), and, on looking through various texts on Fourier series, \[ \cos\frac{2\pi}{T}nt,\quad\cos\frac{2\pi}{T}n(t+\tfrac{1}{2}T), \] \[ \cos(N+\tfrac{1}{2})\frac{2\pi\tau}{T},\quad\sin2\pi\left(\frac{x}{\lambda}-\frac{t}{T}\right). \] Previous versions of \texttt{numerica} employed a setting \verb`()=0,1,2` to parse these outliers from usual practice. From version 3.0.0, this setting has been removed and authors are advised to enclose such arguments in \LaTeX{} braces. The braces do not affect the visual appearance in the \texttt{pdf} but unambiguously tell \texttt{numerica} where the argument begins and ends. \subsubsection{Parsing group III} The only members of this group are \verb`\sum` and \verb`\prod`. A `naked' plus or minus sign is one that is not enclosed by brackets. For parsing group III \begin{enumerate} \item the argument ends \begin{enumerate} \item at the first naked plus or minus sign encountered, or \begin{enumerate} \item first naked comparison sign (or command) encountered, or \item first naked \verb`And` or \verb`Or` sign encountered, or \end{enumerate} \item at the end of the formula. \end{enumerate} \end{enumerate} Almost always this means (a) or (b), and seems to be the instinctive practice. \emph{HMF} has multiple examples in multiple chapters of the argument to a sum ending at a naked plus sign: 7.3.12 \& 7.3.14, 9.1.11 \& 9.1.77, 9.6.35 \& 9.6.43, 11.1.9, \ldots{} (at that point I stopped looking). They were all of the form \[ \sum\text{argument}+\ldots \] A minus sign serving the same purpose was harder to find but \emph{HMF} 10.4.65 \& 10.4.67 are two instances. I considered whether a \verb`\times` or slash fraction sign \verb`/` might end the argument of a sum, but surely we need to allow things like $\sum1/n^{2}$ which rules out the slash and \emph{HMF} 9.9.11 provides two of a number of instances of sum arguments continuing past explicit \verb`\times` signs (at line breaks when a summand spills onto a second line). \noindent{}% \noindent\begin{minipage}[t]{1\columnwidth}% \begin{shaded}% Please note that parenthesizing to clarify the argument of a sum has limitations. Writing \[ \sum\left(\mathtt{}\right)\mathtt{} \] does not necessarily end the summand at the right parenthesis: it ends at the first naked $+$ or $-$ sign encountered (if it is not forced by a \verb`\Q` command or \LaTeX{} braces). Sums \emph{have to} include brackets to cope with factors like $(-1)^{n}$.\end{shaded}% \end{minipage}\medskip{} Because they are evaluated using the same code as sums I (at first unthinkingly) placed products with sums but doubts later intruded. In \emph{HMF} products occur only occasionally and are almost all of the form \[ \prod\left(\text{argument}\right) \] where the argument is bracketed (often with \verb`\left \right` modifiers) and the multiplicand ends with the right bracket. At least twice (\emph{HMF }6.1.25 and 24.2.2.1) an exponent ($-1$) is attached to the right bracket and the argument ends there. Looking further afield, a text on number theory has examples where the argument of the product extends to \emph{three} parenthesised factors, $\prod\left(\text{arg}1\right)\left(\text{arg2}\right)\left(\text{arg3}\right)$ and a number of others where it extends to two. A text on theory of functions has \[ \prod_{n=1}^{\infty}\left(1+\frac{z}{n}\right)e^{z/n} \] although \emph{HMF}, for the same expression, encloses the two factors within (large) square brackets, as if some ambiguity existed as to how far the reach of the \verb`\prod` extended. \emph{Tentatively} I retain products here in the same group as sums. \subsubsection{Parsing group IV} Comparison symbols form this group: \verb`=`, \verb`<`, \verb`>`, \verb`\ne`, \verb`\le`, \verb`\ge`, \verb`\leq`, \verb`\geq`, and the various comparison commands from the \texttt{amssymb} package listed in §\ref{subsec:evalAmssymb-comparisons}. It is the argument on the right-hand side of the relation that needs determining (the argument on the left ends at the comparison). For parsing group IV \begin{enumerate} \item the argument ends at \begin{enumerate} \item the first naked \verb`And` or \verb`Or` encountered, or \item the first naked comparison sign or command encountered, or \item the end of the formula. \end{enumerate} \end{enumerate} \subsubsection{Parsing group V} Logical \verb`And` and logical \verb`Or` are the sole members of this group. It is the right-hand side of the \verb`And` or \verb`Or` command that needs determining. For parsing group V \begin{enumerate} \item the argument ends at \begin{enumerate} \item the first naked \verb`And` or \verb`Or` encountered, or \item the end of the formula. \end{enumerate} \end{enumerate} \subsubsection{Disclaimer} The parsing rules of the different groups are not normative; they are not statements of how mathematical formulas should be written. Rather they attempt to capture regularities in how mathematicians write formulas. It is \emph{how things look and are read in the }\texttt{pdf}, not \LaTeX , that is the guide. You are always free to parenthesize as you see fit, to insert cleave commands (\verb`\q` or \verb`\Q`) or to use \LaTeX{} braces to force outcomes. The rule should always be to write expressions that are clear to the reader of the \texttt{pdf}. An expression that is ambiguous to the reader, even if it fits within the parsing rules, is to be deprecated. The \emph{intent} is that \verb`\eval` can parse unambiguous expressions of the kind that mathematicians, scientists, engineers \emph{do} write, rather than falter over `corner cases'. \section{Using \texttt{numerica} with \protect\LyX} \label{sec:miscLyX}The document processor \LyX{} has a facility that enables snippets from a document to be compiled separately and the results presented to the user without having to compile the entire document. The present document was written in \LyX . The demonstration calculations were evaluated using this \emph{instant preview} facility. To use \texttt{numerica} in \LyX{} go to \textsf{Document \lyxarrow{} Settings \lyxarrow{} LaTeX Preamble} and enter \begin{verbatim} \usepackage{numerica} \end{verbatim} then click \textsf{OK}. You may wish to follow the above line in the preamble with \verb`\nmcReuse{}`: \begin{verbatim} \nmcReuse{} \end{verbatim} In that case, type the extra line and \emph{then} click \textsf{OK}. The additional line ensures all saved values are available in your document from the outset. \subsection{Instant~preview} The instant preview facility of \LyX{} performs mini-\LaTeX{} runs on selected parts of a document (for instance, the mathematical parts) and displays the results in \LyX{} while the user continues to work on the surrounding document.\texttt{ numerica} uses these mini-\LaTeX{} runs to do its evaluations and display their results. That means you get feedback on your calculations almost immediately. To use this facility first ensure that instant preview is turned on. This means selecting \textsf{Tools \lyxarrow Preferences \lyxarrow Look \& Feel \lyxarrow{} Display}, ensuring that the \textsf{Display graphics} checkbox is checked, and against \textsf{Instant preview} selecting \textsf{On}, then clicking \textsf{OK}. \subsubsection{Document location} It also matters where your document is located. You may have your own local or personal texmf tree. If your document is located there, perhaps in the \verb`doc` folder, then not all features of preview will work as expected. Presumably this is because both \LyX{} and your \LaTeX{} distribution (e.g.\ \TeX Live or MiK\TeX ) are interacting with the location and interfere. Move your document to another location which your \LaTeX{} distribution has no interest in, and open it in \LyX{} there. \subsubsection{Global vs local previewing} \label{subsec:miscLyXGlobal-vs-local}Compilation of previews occurs in two distinct modes. \paragraph{Global preview generation:} When a document is opened (and preview is \emph{on}), all previews in the document are formed in sequence in the one \LaTeX{} run. This is the global mode. The mini-\LaTeX{} run may well be substantial. It compiles a \verb`.tex` file that begins with the document's preamble with some additions then comes \verb`\begin{document}`. That is followed by a sequence of preview environments, \begin{verbatim} \begin{preview} \end{preview} \end{verbatim} one for each preview in the document. Finally there is an \verb`\end{document}` statement. Critically, all previews are between the same \verb`\begin{document}`, \verb`\end{document}` statements, and so earlier previews in the sequence can communicate with later ones. \paragraph{Local preview generation:} The other mode in which preview operates is local. Suppose you have your document open and want to add to it, for instance with a simple evaluation, \verb`\eval{x+y}[x=1,y=2]` in an ERT inset in a preview inset. The resulting mini-\LaTeX{} run is of the form \begin{verbatim} \begin{document} \begin{preview} \eval{x+y}[x=1,y=2] \end{preview} \end{document} \end{verbatim} The preamble is as before but only a solitary preview sits between the \verb`\begin` \verb`{document}`, \verb`\end{document}` statements. That preview is isolated from all other, previous previews and will be isolated from all other, later previews. This has implications for the supplementary commands of Chapter~\ref{chap:Supplementary-commands} and means that if you want to transfer information (a macro, a constant, a result) from one preview to another, you need to do it through the preamble or by means of an external file or, in some cases, by forcing a global preview run in which all previews are recompiled between the same \verb`\begin{document}`, \verb`\end{document}` statements. \paragraph{Forcing a global preview run} Closing then opening a document is one way to force a global preview compilation. Another is to change the zoom level. This causes \LyX{} to recompile all previews at the new zoom level. But you may not want to work at the new zoom level. Going back to the old zoom level will force a second recompilation of all previews. For a large document \emph{two} recompilations is too heavy a burden. The secret is to combine a zoom in and a zoom out into one command and attach it to a shortcut. If you go to \textsf{Tools \lyxarrow{} Preferences \lyxarrow{} Editing \lyxarrow{} Shortcuts}, click on the \textsf{New} button and enter \begin{verbatim} command-sequence buffer-zoom-in; buffer-zoom-out \end{verbatim} then assign a shortcut to it (\verb`Alt+Z` for zoom?) you will gain a simple means of forcing a global recompilation of previews. \subsubsection{Mathed} (Mathed = the \LyX{} mathematics editor.) If you have instant preview \emph{on} then one way to use \texttt{numerica} in \LyX{} is to enter an \verb`\eval` command in mathed. Clicking the cursor outside the editor with the mouse or moving it outside with the space bar or arrow keys will then trigger formation of a preview of the editor's contents – a snippet of what will be shown in the \texttt{pdf}. This will be displayed in mathed's place after a generally short `pause for thought' as the mini-\LaTeX{} run progresses behind the scenes. The original expression can be recovered by clicking on the preview. The content of mathed is immediately displayed and can be edited. \paragraph{\protect\LaTeX{} braces~\{~~\}} \LyX{} does not support \texttt{numerica}'s \verb`\eval` command `out of the box' as it does, say, \verb`\frac` or \verb`\sqrt`. To use the \verb`\eval` command in mathed you will need to supply the braces used to delimit its mandatory argument. (For \verb`\frac` and \verb`\sqrt` by contrast, \LyX{} supplies these automatically in the form of blue-outlined boxes.) Unfortunately the \verb`{` key\footnote{\textsf{Shift+{[}} on my keyboard.} does not insert a left brace into the document but rather an escaped left brace \verb`\{` as you can see by looking at \textsf{View \lyxarrow{} Code Preview Pane}. Escaped braces like this are used for grouping terms in \emph{mathematics}; they are not the delimiters of a \LaTeX{} argument. The brace delimiters for \LaTeX{} arguments are entered in mathed by typing a backslash \textsf{\textbackslash{} }then a left brace\textsf{ \{} – two separate key presses rather than a single combined press. This enters a balanced pair of (unescaped) braces with the cursor sitting between them waiting for input. Alternatively, if you have already written an expression that you want to place between braces, select it, then type \textsf{\textbackslash{} }then\textsf{ \{}. \subsubsection{Preview insets} There are problems with using mathed for calculations. \begin{itemize} \item Expressions entered in mathed are necessarily of the form \verb`$ \eval... $` or more generally \verb`delimiter` \verb`\eval...` \verb`delimiter`. But you may wish to wrap the \verb`\eval` command \emph{around} the math delimiters to produce a \emph{formula=result} form of display. In mathed the only way to effect such a display is to write the \emph{formula= }part yourself – which may involve no more than copy and paste but is still additional mouse work/key pressing. \item Mathed does not accept carriage returns. If you want to format a complicated expression for readability by breaking it into separate lines, you can't. The expression is jammed into the one line, along with the settings option content and the vv-list, often extending well beyond the edge of the screen. \end{itemize} For these reasons I have come to prefer \emph{not} using mathed for calculations but instead to use preview insets wrapped around \TeX -code (ERT) insets. \LyX{} uses the shortcut \textsf{Ctrl+L} to insert an ERT inset. Since \LyX{} now does no printing itself, the shortcut \textsf{Ctrl+P} that was formerly used for printing is available for other purposes. On my keyboard, the \textsf{P} key lies diagonally up and to the right but adjacent to the \textsf{L} key. I suggest assigning \textsf{Ctrl+P} to inserting a preview inset. Then typing \textsf{Ctrl+P Ctrl+L} – which means holding the \textsf{Ctrl} key down and tapping two diagonally adjacent keys, \textsf{P} followed immediately by \textsf{L} – will insert an ERT inset inside a preview inset with the cursor sitting inside the ERT inset waiting for input. In the ERT inset you can enter carriage returns, and so format complicated expressions. You can place the vv-list on a separate line or onto consecutive lines. And when you have finished, clicking outside the preview inset will trigger preview into doing its thing and present the result `before your eyes'. To assign the suggested shortcut, go to \textsf{Tools \lyxarrow{} Preferences \lyxarrow{} Editing \lyxarrow{} Shortcuts}. Under \textsf{Cursor, Mouse and Editing Functions} in the main window on the right, scroll down until you come to \textsf{preview-insert}, select it, then click \textsf{Modify}. Now press \textsf{Ctrl+P}. The shortcut will magically appear in the greyed, depressed key.\textsf{ }Click \textsf{OK} and then \textsf{OK} in the \textsf{Preferences} window to close it. (Most of the examples in this document have been evaluated in this way, using \textsf{Ctrl+P Ctrl+L.)} \subsubsection{Errors } Instant preview will display error messages generated by \texttt{numerica} in \LyX{} just as it does the results of calculations. Clicking on the message will show the underlying expression which can then be edited. However \LaTeX{} errors will \emph{not} produce a preview; formation of the preview will stall. To find precisely what has gone wrong, you will need to look at the \LaTeX{} log, but not the log of the overall document; rather the \emph{preview} log. \paragraph{Temporary directory of \protect\LyX} Unfortunately this is tucked away in a temporary directory and is not immediately accessible in \LyX{} (unlike the main \LaTeX{} log from \textsf{Document \lyxarrow{} \LaTeX{} Log}). When \LyX{} is started, it sets up a temporary directory in which to perform various tasks. On Windows systems this will be located in \texttt{C:\textbackslash Users\textbackslash \textbackslash AppData\textbackslash Local\textbackslash Temp} and will have a name like \texttt{lyx\_tmpdir.XOsSGhBc1344}. One of the tasks \LyX{} uses this temporary directory for is to create preview images when a document is opened. If you look inside \LyX 's temporary directory when a document is first loaded, you will see a subdirectory created, with a name like \texttt{lyx\_tmpbuf0}. There may already be such directories there, in which case the number on the end will be greater than \texttt{0} – it depends on whether other documents are or have been open in the current instance of \LyX . Inside the appropriate \texttt{lyx\_tmpbuf}\texttt{\emph{n}} folder will be the preview log with a name like \texttt{lyxpreviewZL1344.log}. It will usually be accompanied by other files with extensions like \texttt{.dvi}, \texttt{.tex}, and – depending on the number of previews in your document – a number, perhaps a lot, of image files with the extension \texttt{.png}, each one of which is a preview. For a document just loaded there will be only the one preview log, but if you have added preview insets or math insets to your document\textsf{ }in the current editing session there will be a number of such logs and you will need to determine the relevant one by the time stamp. The log files are text files and can be opened in a text editor. The relevant part of the log is towards the end (just before the final statistical summary) where you will find a list of entries like \texttt{Preview: Snippet 1 641947 163840 7864588}. If there is an error, it will be noted here among these snippets and will generally make clear what needs remedying. \paragraph{CPU usage, \protect\LaTeX{} processes} It is possible when a preview stalls that the \LaTeX{} process associated with the preview will continue to run, using CPU cycles, slowing overall computer performance, and perhaps resulting in extra fan use giving a different sound to the computer. In Windows 10, the \textsf{Task Manager} (\textsf{Ctrl+Shift+esc}) under the \textsf{Details} tab shows the current executables running. The \textsf{CPU} column will show which processes are preoccupying the CPU. Check whether one or more of these processes looks \LaTeX -related (e.g.\ \texttt{latex.exe} or \texttt{pdflatex.exe}, or \texttt{miktex-pdftex.exe} if using MiK\TeX ). Click the \textsf{Name} column to sort the processes by name and look for the relevant name in the list, select it, and end the process (click the \textsf{End Task} button). I am not familiar with the corresponding situation on Linux or Mac. \subsubsection{Hyperref support vs speed} If you want the \texttt{pdf} produced from your document to support hyperref links and show an outline window in your \texttt{pdf} viewer (generally placed on the left in the viewer) then you need to ensure the checkbox at \textsf{Document Settings \lyxarrow{} PDF Properties \lyxarrow{} Use Hyperref Support} is indeed checked. But you don't need to do this until the final compilation of the document. The advantage of leaving this until the last is that in a large document with many previews the time for preview generation is essentially halved. If hyperref support is enabled, preview generation not only creates all the individual image files that are the previews (files of extension \verb`.png`) but also requires the compilation of a single \texttt{pdf} document showing all the previews in sequence. (Like the previews, the \texttt{pdf} document `hides' in the termporary directory where \LyX{} does its work.) In other words, \emph{two} images are created for each preview, the \verb`.png` image which is the one \LyX{} displays, and another image buried inside the \texttt{pdf} of all images. That second step does not occur if hyperref support is disabled. In a small document, this is not going to matter; in a large document it becomes significant. It is well worth temporarily turning off hyperref support and then, when the time for final compilation comes, turning it back on. \subsection{Supplementary commands in \protect\LyX} There are some difficulties using the supplementary commands successfully with instant preview. \subsubsection{Reuse of earlier previews} One is that whenever \LyX{} has generated a preview image for a particular \LaTeX{} expression, it will use that same image whenever it meets that same \LaTeX{} expression later. That means that a statement like \verb`\macros[view]{}` and the same statement later will display the same image, even though there may have been macros defined or freed in between. The same goes for all the other supplementary functions, including, for example, \verb`\info{sum}`. A second instance of \verb`\info{sum}` will display the image generated by the first instance even though further infinite sums may have been evaluated between the \verb`\info` statements. The remedy is to make some small but insignificant difference to the \LaTeX{} expression in the second instance – generally a change in white space will do. For example: first time \verb`\macros[view]{}`, second time \verb`\macros[view]{ }` where a space has been inserted between the braces; or: first time \verb`\info{sum}`, second time \verb`\info{ sum}` where a space has been inserted before \verb`sum`. This will ensure \LyX{} doesn't fall back on the previously generated image. \subsubsection{\textquoteleft Stalled\textquoteright{} previews} It is possible to put content into an ERT inset inside a preview inset (\textsf{Ctrl+P Ctrl+L}) and for nothing to happen. The preview has apparently stalled. Certainly this can be the case if there is an error in the input (e.g.\ a missing brace) but it also occurs if there is no output to display. For instance \verb`\constants` \verb`{ c=300000000 }` does not produce any visual output. There is nothing for the preview to display and so the preview inset sits there, apparently stalled. This is a security measure for previews in \LyX{} to provide at least some guard against malicious code being run in the preview. If the preview resolved, it would disappear completely from view in the \LyX{} window. If you find the visual appearance of such apparently stalled previews distracting, the addition of some displayable content to the preview will result in it resolving to that content; the content could be as small as a full stop. \subsubsection{Using \texttt{\textbackslash nmcMacros}} As noted earlier, previews are mini-\LaTeX{} runs, either local or global. Each local preview is of the form \begin{verbatim} \begin{document} \begin{preview} \end{preview} \end{document} \end{verbatim} Whatever goes into or comes out of the preview is isolated from any other local preview, unless it is through the preamble or an external file. Sometimes a global preview run can overcome this problem for then all the previews lie between the same \verb`\begin{document}`, \verb`end{document}` statements. However, this does not help with macro definitions. \verb`\def`, \verb`\newcommand`, \verb`\NewDocumentCommand` all provide \emph{local} definitions which remain trapped within their own \verb`\begin{preview}`, \verb`\end{preview}`) statements. Another preview, say containing an \verb`\eval` command, between a different pair of \verb`\begin{preview}`, \verb`\end{preview}`) statements, will not know about the macro definition. There are (at least) three ways out: \begin{enumerate} \item Confine everything to the same preview inset: the definition of a macro, the \verb`\macros` statement, and the use of the macro in an \verb`\eval` command. \item Confine macro definitions to the preamble (\textsf{Document \lyxarrow{} Settings \lyxarrow{} \LaTeX{} Preamble}). \item Within previews use \verb`\gdef` (or \verb`\global\def`) exclusively for making your macro definitions; this makes the macro available to all later previews. \end{enumerate} \subsubsection{Using \texttt{\textbackslash nmcConstants}} Because \verb`\nmcConstants` doesn't use \verb`\def` or \verb`\newcommand` or \verb`\NewDocumentCommand` it is not subject to the same localisation problem as \verb`\nmcMacros`, but the reach of a \verb`\constants` command will still be confined to its own preview unless a \emph{global} preview run is forced; see above §\ref{subsec:miscLyXGlobal-vs-local}. \subsubsection{Using \texttt{\textbackslash nmcReuse}} As noted earlier, \LyX{} creates its previews in a temporary directory, not the document directory. If you want to save values from your current document – say, \texttt{mydoc.lyx} – to \texttt{mydoc.nmc} then you do so as described earlier (§\ref{sec:supplReuse}), but the file \texttt{mydoc.nmc} containing the saved results will be located in the temporary directory. When \LyX{} is closed the file will be deleted along with all the other contents of that directory. Fortunately \LyX{} has a copying mechanism for getting files out of the temporary directory and into the document directory. When a document is exported – say to \texttt{pdf} – it is possible to specify a \emph{copier} to automatically copy back to the document directory or subdirectory various files in the temporary directory. We want the \texttt{.nmc} file containing the saved values to be copied back. Go to \textsf{Tools \lyxarrow{} Preferences \lyxarrow{} File Handling \lyxarrow{} File Formats} and find \textsf{PDF (pdflatex)} (assuming export to \texttt{pdf} by this route) in the list of formats. In\textsf{ }the \textsf{Copier} slot of the dialogue insert the following line of code: \begin{verbatim} python -tt $$s/scripts/ext_copy.py -e nmc,pdf -d $$i $$o \end{verbatim} \verb`ext_copy.py` is a python script that is supplied with \LyX . The \texttt{-e nmc,pdf -d} part of the line tells \texttt{ext\_copy.py} that on export to \texttt{pdf} by the \texttt{pdflatex} route\texttt{ }to copy any files with the extensions \texttt{.nmc} or \texttt{.pdf} from the temporary directory where \LyX{} does its work back to the document directory – the \verb`-d` option (which became available with \LyX{} 2.3.0). But if you have a complex document, it may take too much time to want to export to pdf before closing \LyX , particularly if there are a lot of evaluations in the document. Much faster is to export to \emph{plain text}, not because you want a plain text version of your document but because it too can be used to trigger the copier mechanism. Go to \textsf{Tools \lyxarrow{} Preferences \lyxarrow{} File Handling \lyxarrow{} File Formats} and find \textsf{Plain text} in the list of formats. In the \textsf{Copier} slot enter \begin{verbatim} python -tt $$s/scripts/ext_copy.py -e nmc -d $$i $$o \end{verbatim} The only difference from the previous copier command is the absence of \texttt{pdf}.\footnote{I'm assuming that you don't actually want the plain text version of the file copied back. If you do, then change \texttt{-e nmc} to \texttt{-e nmc,txt}.} This will copy \texttt{mydoc.nmc} with its saved values from the temporary directory back to the document directory. To effect the export, go to \textsf{File \lyxarrow{} Export }and find \textsf{Plain text} in the list of formats and click on it. A shortcut would be nice. For that go to \textsf{Tools \lyxarrow{} Preferences \lyxarrow{} Editing \lyxarrow{} Shortcuts}, click on \textsf{New}, enter \texttt{buffer-export text} in the \textsf{Function:} slot, click on the blank key against \textsf{Shortcut:} and type your shortcut. You may have to try a number before you find one that hasn't already been assigned. (I'm using \textsf{Ctrl+}; for no particular reason beyond the fact that it fits under the fingers easily and saving values to the document directory has a punctuation-like feel to it, a pause in the process of writing.) It is now an easy matter to press the shortcut at the end of a \LyX{} session to copy all the values saved in \texttt{mydoc.nmc} back to a file of the same name in the document directory. And it is brisk, not least because plain text export ignores ERT insets (and hence preview insets wrapped around ERT insets), nor does it evaluate \verb`\eval` commands in math insets. \subsubsection{A final tweak?} But one still needs to \emph{remember} to press the shortcut. The thought arises: can \emph{closing} the current document trigger the copying process? \LyX{} provides a means of linking two commands and assigning a keyboard shortcut to them with its \texttt{command-sequence} \LyX{} function. I suggest assigning a shortcut\textsf{ }to \begin{verbatim} command-sequence buffer-export text; view-close \end{verbatim} Indeed, why not reassign the current shortcut for \texttt{view-close},\texttt{ }which is \textsf{Ctrl+W} on my system, to this command sequence? (I use the \texttt{cua} key bindings – check the \textsf{Bind file:} slot in \textsf{Tools \lyxarrow{} Preferences \lyxarrow{} Editing \lyxarrow{} Shortcuts}.) Please note, however, that \emph{this will work as intended only from \LyX{} 2.4.0}.\footnote{Long-planned and initially due for release in 2021 but still (August 2023) not released. But a beta3 version is now available from \url{https://ftp.lip6.fr/pub/lyx/devel/lyx-2.4/}} For \LyX{} 2.3 and earlier, the command sequence will generally fail because of `asynchronous' processing – \texttt{buffer-export }and \texttt{view-close} use different threads and the latter may well start before the former is complete. From \LyX{} 2.4.0 this defect has been fixed. You press your shortcut, the export to plain text occurs and the \texttt{.nmc} file is copied back to the document directory, then the current view is closed. Note that in the other direction, the \verb`.nmc` file in your document directory is \emph{automatically} copied to the temporary directory when needed. Nothing needs to be done by you, the user. \subsection{Use of \protect\LyX{} notes} The central fact about a \LyX{} note is that it does not contribute to the pdf. But instant preview still works there. This suggests a possibility: that a calculation be performed within a \LyX{} note and the result saved using \verb`\nmcReuse` within the same note. The saved value is now available \emph{from file} for use elsewhere in the document. In this way, some selected content from a LyX note \emph{can} find its way into the pdf when the document is compiled. \chapter{Reference summary} \section{Package options} \begin{itemize} \item \verb`comma` sets the comma as the decimal point; items in the variable=value list must then be separated by semicolons; arguments in $n$-ary functions must also be separated by semicolons; by default formulas in a multi-formula calculation should also be separated by a semicolon; \item \verb`rounding`=$n$ sets the default rounding value to the integer $n$; \item \verb`approx` replaces the default \verb`=` between formula and result in (some) displays with \verb`\approx` (displaying as $\approx$; the \verb`eq=` setting is still available to change the symbol for individual calculations). \end{itemize} \section{Commands defined in \texttt{numerica}} \begin{enumerate} \item \texttt{\textbackslash nmcEvaluate, \textbackslash eval } \item \texttt{\textbackslash q, \textbackslash Q }(`cleave' commands) \item \texttt{\textbackslash nmcInfo, \textbackslash info} \item \texttt{\textbackslash nmcMacros, \textbackslash macros} \item \texttt{\textbackslash nmcConstants, \textbackslash constants} \item \texttt{\textbackslash nmcReuse, \textbackslash reuse} \end{enumerate} Provided they have not already been defined when \texttt{numerica} is loaded, the following commands are defined in \texttt{numerica} using \verb`\DeclareMathOperator` from \texttt{amsmath}: \begin{enumerate} \item \texttt{\textbackslash arccsc, \textbackslash arcsec, \textbackslash arccot} \item \texttt{\textbackslash csch, \textbackslash sech} \item \texttt{\textbackslash asinh, \textbackslash acosh, \textbackslash atanh, \textbackslash acsch, \textbackslash asech, \textbackslash acoth} \item \texttt{\textbackslash arsinh, \textbackslash arcosh, \textbackslash artanh, \textbackslash arcsch, \textbackslash arsech, \textbackslash arcoth} \item \texttt{\textbackslash arcsinh, \textbackslash arccosh, \textbackslash arctanh, \textbackslash arccsch, \textbackslash arcsech, \textbackslash arccoth} \item \texttt{\textbackslash sgn, \textbackslash lb} \end{enumerate} Provided they have not already been defined, the following commands are defined in \texttt{numerica} using \verb`\DeclarePairedDelimiter` from \texttt{mathtools}: \begin{verbatim} \abs, \ceil, \floor \end{verbatim} Provided they have not already been defined, the following commands are defined in \texttt{numerica} using \texttt{\textbackslash ProvideDocumentCommand} \begin{verbatim} \comma, \equals, \degree \end{verbatim} The following commands have been redefined in \texttt{numerica} to give more spacing around the underlying \verb`\wedge` and \verb`\vee` symbols: \begin{verbatim} \land, \lor \end{verbatim} \section{\textquoteleft Digestible\textquoteright{} content} \texttt{numerica} knows how to deal with the following content, meaning that any of these elements occurring within an \verb`\eval` command should not of itself cause a \texttt{numerica} error. Not all formatting commands affect display of the output. \begin{enumerate} \item variable names (sequences of tokens given values in the variable=value list) \item digits, decimal point \begin{enumerate} \item \texttt{1, 2, 3, 4, 5, 6, 7, 8, 9, 0, . }or \texttt{,} (if \texttt{comma} package option used) \end{enumerate} \item constants \begin{enumerate} \item \texttt{e, \textbackslash pi, \textbackslash gamma, \textbackslash phi, \textbackslash deg, \textbackslash infty} \end{enumerate} \item arithmetic operators \begin{enumerate} \item \texttt{+, -, {*}, /, \textasciicircum , \textbackslash times, \textbackslash cdot, \textbackslash div} \end{enumerate} \item logical operators \begin{enumerate} \item \texttt{\textbackslash wedge, \textbackslash land, \textbackslash vee, \textbackslash lor, \textbackslash neg, \textbackslash lnot} \end{enumerate} \item degree symbol/switch \begin{enumerate} \item \texttt{\textbackslash degree} (possibly from package \texttt{gensymb}) \end{enumerate} \item comparisons \begin{enumerate} \item \texttt{=, <, >, \textbackslash ne, \textbackslash neq, \textbackslash le, \textbackslash leq, \textbackslash ge, \textbackslash geq} \item (if \texttt{amssymb} loaded) \texttt{\textbackslash nless, \textbackslash ngtr, \textbackslash geqq, \textbackslash geqslant, \textbackslash leqq, \textbackslash leqslant, \textbackslash ngeq, \textbackslash ngeqq, \textbackslash ngeqslant, \textbackslash nleq, \textbackslash nleqq, \textbackslash nleqslant} \end{enumerate} \item brackets, bracket-like elements, modifiers \begin{enumerate} \item \texttt{( ), {[} {]}, \textbackslash\{ \textbackslash\}; \textbackslash lparen \textbackslash rparen} (from \texttt{mathtools})\texttt{; \textbackslash lbrack \textbackslash rbrack, \textbackslash lbrace \textbackslash rbrace} \item \texttt{\textbackslash lvert \textbackslash rvert, \textbackslash lfloor \textbackslash rfloor, \textbackslash lceil \textbackslash rceil} \item \texttt{| |} (cannot be nested, deprecated) \item \texttt{\textbackslash left \textbackslash right;} \texttt{\textbackslash mleft \textbackslash mright, \textbackslash mleftright, \textbackslash mleftrightrestore} (if \texttt{mleftright} loaded) \item \texttt{\textbackslash bigl \textbackslash bigr, \textbackslash Bigl \textbackslash Bigr, \textbackslash biggl \textbackslash biggr, \textbackslash Biggl \textbackslash Biggr} \item \texttt{\textbackslash middle }(if \texttt{mleftright} loaded)\texttt{;\textbackslash big, \textbackslash Big, \textbackslash bigg, \textbackslash Bigg} \item \texttt{.} \texttt{/ |} (used with a modifier) \item \texttt{\textbackslash abs{[}{]}\{\}, \textbackslash abs{*}\{\}, \textbackslash floor{[}{]}\{\}, \textbackslash floor{*}\{\}, \textbackslash ceil{[}{]}\{\}, \textbackslash ceil{*}\{\}} \end{enumerate} \item unary functions (in the mathematical sense) \begin{enumerate} \item \texttt{\textbackslash sin, \textbackslash cos, \textbackslash tan, \textbackslash csc, \textbackslash sec, \textbackslash cot} \item \texttt{\textbackslash arcsin, \textbackslash arccos, \textbackslash arctan, arccsc, \textbackslash arcsec, \textbackslash arccot } \item \texttt{\textbackslash sin\textasciicircum\{-1\}, \textbackslash cos\textasciicircum\{-1\}, \textbackslash tan\textasciicircum\{-1\}, \textbackslash csc\textasciicircum\{-1\}, \textbackslash sec\textasciicircum\{-1\}, \textbackslash cot\textasciicircum\{-1\}} \item \texttt{\textbackslash sinh, \textbackslash cosh, \textbackslash tanh, \textbackslash csch, \textbackslash sech, \textbackslash coth } \item \texttt{\textbackslash asinh, \textbackslash acosh, \textbackslash atanh, \textbackslash acsch, \textbackslash asech, \textbackslash acoth, \textbackslash arsinh, \textbackslash arcosh, \textbackslash artanh, \textbackslash arcsch, \textbackslash arsech, \textbackslash arcoth, \textbackslash arcsinh, \textbackslash arccosh, \textbackslash arctanh, \textbackslash arccsch, \textbackslash arcsech, \textbackslash arccoth} \item \texttt{\textbackslash sinh\textasciicircum\{-1\}, \textbackslash cosh\textasciicircum\{-1\}, \textbackslash tanh\textasciicircum\{-1\}, \textbackslash csch\textasciicircum\{-1\}, \textbackslash sech\textasciicircum\{-1\}, \textbackslash coth\textasciicircum\{-1\}} \item \texttt{\textbackslash exp, \textbackslash lb, \textbackslash lg, \textbackslash ln, \textbackslash log, \textbackslash log\_\{\}, \textbackslash sgn, \textbackslash surd} \item \texttt{\textbackslash sqrt\{\}, \textbackslash abs{[}{]}\{\}, \textbackslash abs{*}\{\}, \textbackslash floor{[}{]}\{\}, \textbackslash floor{*}\{\}, \textbackslash ceil{[}{]}\{\}, \textbackslash ceil{*}\{\}} \item \texttt{!, !! }(both with a prepended argument) \end{enumerate} \item binary functions \begin{enumerate} \item \texttt{\textbackslash tfrac\{\}\{\}, \textbackslash frac\{\}\{\}, \textbackslash dfrac\{\}\{\}, \textbackslash sfrac }(if \texttt{xfrac} loaded) \item \texttt{\textbackslash tbinom\{\}\{\}, \textbackslash binom\{\}\{\}, \textbackslash dbinom\{\}\{\}} \item \texttt{\textbackslash sqrt{[}{]}\{\}} \end{enumerate} \item $n$-ary functions \begin{enumerate} \item \texttt{\textbackslash min, \textbackslash max, \textbackslash gcd} \end{enumerate} \item sum, prod \begin{enumerate} \item \texttt{\textbackslash sum\_\{\}\{\}\textasciicircum\{\}, \textbackslash prod\_\{\}\{\}\textasciicircum\{\} } \end{enumerate} \item formatting commands \begin{enumerate} \item \texttt{,} (comma, in $n$-ary functions) \item \texttt{\{\}, \textbackslash\textbackslash , \&, \textbackslash to} \item \texttt{\textbackslash begin\{\}, \textbackslash end\{\}, \$, \textbackslash{[}, \textbackslash{]}} \item \texttt{\textbackslash dots, \textbackslash ldots, \textbackslash cdots} \item \texttt{\textbackslash{} , \textbackslash , {}, \textbackslash ;, \textbackslash :, \textbackslash !, \textbackslash >} \item \texttt{\textbackslash thinspace, \textbackslash medspace, \textbackslash thickspace,} \item \textbackslash\texttt{negthinspace, \textbackslash negmedspace, \textbackslash negthickspace,} \item \textbackslash\texttt{hspace{*}\{\}, \textbackslash mspace\{\},} \item \texttt{\textbackslash quad, \textbackslash qquad , \textbackslash hfill, \textbackslash hfil} \item \texttt{\textbackslash phantom\{\}, \textbackslash vphantom\{\}, \textbackslash hphantom\{\}} \item \texttt{\textbackslash xmathstrut{[}{]}\{\}} \texttt{, \textbackslash splitfrac\{\}\{\}, \textbackslash splitdfrac\{\}\{\} }(from \texttt{mathtools}), \texttt{\textbackslash mathstrut} \item \texttt{\textbackslash displaystyle, \textbackslash textstyle, \textbackslash scriptstyle, \textbackslash scriptscriptstyle} \item \texttt{\textbackslash label\{\}, \textbackslash ensuremath\{\}, \textbackslash text\{\}, \textbackslash mbox\{\}, \textbackslash smash\{\}} \item \texttt{\textbackslash color{[}{]}\{\}, \textbackslash textcolor{[}{]}\{\}\{\}} \item \texttt{\textbackslash mkern, \textbackslash mskip} \end{enumerate} \item font commands \begin{enumerate} \item \texttt{\textbackslash mathrm\{\}, \textbackslash mathit\{\}, \textbackslash mathcal\{\}, \textbackslash mathtt\{\}, \textbackslash mathbf\{\}, \textbackslash mathbb\{\}, \textbackslash mathsf\{\}, \textbackslash mathfrak\{\}, \textbackslash mathscr\{\}} \item \texttt{\textbackslash mathnormal\{\}, \textbackslash boldsymbol\{\}} \item \texttt{\textbackslash textrm\{\}, \textbackslash textsf\{\}, \textbackslash texttt\{\}, \textbackslash textit\{\}, \textbackslash textsl\{\}, \textbackslash textbf\{\}, \textbackslash textsc\{\}} \end{enumerate} \end{enumerate} \section{Settings} \subsection{Functional settings} \begin{center} \begin{center} \begin{tabular}{>{\raggedright}p{1.5cm}>{\raggedright}p{1.5cm}>{\raggedright}p{3cm}>{\raggedright}p{1.5cm}>{\raggedright}p{1.5cm}} \toprule {\small key} & {\small type} & {\small meaning} & {\small default} & {\small initial}\tabularnewline \midrule {\small\texttt{dbg}} & {\small int} & {\small debug data} & & {\small\texttt{0}}\tabularnewline {\small\texttt{view}} & & {\small\texttt{dbg=1}} & {\small\texttt{dbg=1}} & \tabularnewline {\small\texttt{\textasciicircum}} & {\small char} & {\small exp. mark for sci. notation input} & {\small\texttt{e}} & \tabularnewline {\small\texttt{xx}} & {\small int (0/1)} & {\small accept multi-token variables} & & {\small\texttt{1}}\tabularnewline \multirow{2}{1.5cm}{\texttt{ff}} & \multirow{2}{1.5cm}{{\small char}} & \multirow{2}{3cm}{{\small main arg. multi- formula delimiter}} & \multicolumn{2}{l}{{\small\texttt{, }}{\small (if decimal dot)}}\tabularnewline & & & \multicolumn{2}{l}{{\small\texttt{; }}{\small (if decimal comma)}}\tabularnewline {\small\texttt{1s2}} & {\small int (0/1)} & {\small allow spaced digit groups in numbers} & {\small\texttt{1}} & {\small\texttt{0}}\tabularnewline {\small\texttt{/min}} & {\small$\text{int}\ge1$} & {\small fraction form denom- inator search start} & & {\small\texttt{1}}\tabularnewline {\small\texttt{/max}} & {\small$\text{int}\ge1$} & {\small fraction form denom- inator search end} & & {\small\texttt{200}}\tabularnewline {\small\texttt{vv@}} & \multirow{3}{1.5cm}{{\small int (0/1)}} & \multirow{3}{3cm}{{\small vv-list calculation mode}} & \multirow{3}{1.5cm}{} & \multirow{3}{1.5cm}{{\small\texttt{0}}}\tabularnewline \multirow{2}{1.5cm}{{\small\texttt{vvmode}}} & & & & \tabularnewline & & & & \tabularnewline {\small\texttt{o}} & {\small int (0/1)} & {\small trig. function args in degrees} & {\small\texttt{1}} & {\small\texttt{0}}\tabularnewline {\small\texttt{log}} & {\small num} & {\small base of logs for }{\small{\small\verb`\log`}} & & {\small\texttt{10}}\tabularnewline {\small\texttt{S+}} & {\small int} & {\small extra rounding, sums} & & {\small\texttt{2}}\tabularnewline {\small\texttt{S?}} & {\small$\text{int}\ge0$} & {\small number of query terms, sums} & & {\small\texttt{0}}\tabularnewline {\small\texttt{P+}} & {\small int} & {\small extra rounding, products} & & {\small\texttt{2}}\tabularnewline {\small\texttt{P?}} & {\small$\text{int}\ge0$} & {\small number of query terms, products} & & {\small\texttt{0}}\tabularnewline \midrule {\small\texttt{()}} & \multicolumn{4}{l}{{\small obsolete; see §\ref{sec:settinsDeprecatedObsoleteOptions}}}\tabularnewline {\small\texttt{reuse}} & \multicolumn{4}{l}{{\small obsolete; see §\ref{sec:settinsDeprecatedObsoleteOptions}}}\tabularnewline {\small\texttt{{*}}} & \multicolumn{4}{l}{{\small obsolete; see §\ref{sec:settinsDeprecatedObsoleteOptions}}}\tabularnewline \bottomrule \end{tabular} \par\end{center} \par\end{center} \subsubsection{Debug settings} \begin{itemize} \item \verb`dbg=0`\texttt{ }turns off the debug function, displays the result or error message (this is the initial value); \item \verb`dbg=1`\texttt{ }equivalent to \verb`dbg=2*3*5*7*11` for \verb`\eval`; \item \verb`dbg=2` displays the formula after multi-token variables have been converted to their single token form, \verb`\nmc_a`, \verb`\nmc_b`, etc.; \item \verb`dbg=3` displays the vv-list after multi-token variables have been converted to their single token form; \item \verb`dbg=5` displays the stored variables and their values \emph{after} evaluation (\verb`dbg=3` lists the values as expressions); \item \verb`dbg=7` displays the formula after it has been fp-ified but before it has been fed to \texttt{l3fp} to evaluate; \item \verb`dbg=11` displays the \LaTeX{} form of the final display; it will contain, \emph{inter alia}, the numerical result. \end{itemize} \subsection{Display settings} \begin{tabular}{>{\raggedright}p{1cm}>{\raggedright}p{1.5cm}>{\raggedright}p{3.5cm}>{\centering}p{1.5cm}>{\centering}p{1.5cm}} \toprule {\small key} & {\small type} & {\small meaning} & {\small default} & {\small initial}\tabularnewline \midrule \texttt{f} & {\small int (0/1)} & {\small show/hide formula} & & \tabularnewline {\small\texttt{p}} & {\small token(s)} & {\small concluding punctuation} & {\small\texttt{,}} & \tabularnewline {\small\texttt{pp}} & {\small token(s)} & {\small multi-formula inter- result punctuation} & {\small\texttt{,}} & \tabularnewline \cmidrule{1-1} {\small\texttt{env}} & {\small token(s)} & {\small math environment} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{arg}} & {\small token(s)} & {\small arg. for }{\small\texttt{-at}}{\small , }{\small\texttt{array}}{\small{} envs} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{eq}} & {\small token(s)} & {\small relation symbol} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{vv}} & {\small token(s)} & {\small vv-list specification} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{sep}} & {\small token(s)} & {\small separator between multi-formula results} & \multicolumn{2}{c}{{\small see Table~\ref{tab:settingsEnvironment-defaults}}}\tabularnewline {\small\texttt{\textbackslash\}}} & {\small token(s)} & {\small right bracket for inner math environments} & {\small\textbackslash{} }{\small\texttt{\textbackslash\}}} & \tabularnewline \cmidrule{1-1} {\small\texttt{vvi}} & \multicolumn{4}{l}{{\small deprecated; use }{\small\texttt{vv}}}\tabularnewline {\small\texttt{vvd}} & \multicolumn{4}{l}{{\small deprecated; use }{\small\texttt{vv}}}\tabularnewline \bottomrule \end{tabular} \subsection{Environment settings} \begin{tabular}{lccV{\linewidth}l} \toprule {\small\texttt{env}} & {\small rem/}{\small\texttt{arg}} & {\small\texttt{eq}} & {\small\texttt{vv}} & {\small\texttt{sep}}\tabularnewline \midrule {\small\texttt{\$}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{=}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 12muplus}}~\linebreak{} {\small\texttt{6muminus9mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{{\small\texttt{\textbackslash quad}}}\tabularnewline {\small\texttt{\textbackslash (}} & & & & \tabularnewline {\small\texttt{math}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{\textbackslash{[}}} & & {\small\texttt{=}} & \begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth} & {\small\texttt{\textbackslash{]}\textbackslash{[}}}\tabularnewline \cmidrule{1-1} {\small\texttt{displaymath}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{=}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{\textbackslash end\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}}~\linebreak{} {\small\texttt{\textbackslash begin\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}} \end{cellvarwidth}}\tabularnewline {\small\texttt{equation}} & & & & \tabularnewline {\small\texttt{equation{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{multline}} & \multirow{2}{*}{\begin{cellvarwidth}[t] \centering {\small\texttt{\textbackslash eval}}{\small{} in }\linebreak{} {\small{} }{\small\texttt{multline}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{=}}} & \multirow{2}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{\textbackslash hfill\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{multline{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{multline}} & \multirow{2}{*}{\begin{cellvarwidth}[t] \centering {\small\texttt{multline}}~\linebreak{} {\small in }{\small\texttt{\textbackslash eval}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{=}}} & \multirow{2}{*}{{\small\texttt{,\textbackslash\textbackslash (vv)}}} & \multirow{2}{*}{\begin{cellvarwidth}[t] {\small\texttt{\textbackslash end\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}}~\linebreak{} {\small\texttt{\textbackslash begin\{}}{\small\texttt{\emph{env}}}{\small\texttt{\}}} \end{cellvarwidth}}\tabularnewline {\small\texttt{multline{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{eqnarray}} & \multirow{2}{*}{} & \multirow{2}{*}{{\small\texttt{\&=\&}}} & \multirow{2}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{2}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{eqnarray{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{align}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{\&=}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 36mu}}~\linebreak{} {\small\texttt{minus24mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{align{*}}} & & & & \tabularnewline {\small\texttt{aligned}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{flalign}} & \multirow{2}{*}{} & \multirow{2}{*}{{\small\texttt{\&=}}} & \multirow{2}{*}{{\small\texttt{,\&(vv)}}} & \multirow{2}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{flalign{*}}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{gather}} & \multirow{3}{*}{} & \multirow{3}{*}{{\small\texttt{\&=\&}}} & \multirow{3}{*}{\begin{cellvarwidth}[t] {\small\texttt{,\textbackslash mskip 12muplus}}~\linebreak{} {\small\texttt{6muminus9mu(vv)}} \end{cellvarwidth}} & \multirow{3}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{gather{*}}} & & & & \tabularnewline {\small\texttt{gathered}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{alignat}} & \multirow{3}{*}{{\small\texttt{2}}} & \multirow{3}{*}{{\small\texttt{\&=\textbackslash ;\&}}} & \multirow{3}{*}{{\small\texttt{,\textbackslash qquad\&(vv)}}} & \multirow{3}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{alignat{*}}} & & & & \tabularnewline {\small\texttt{alignedat}} & & & & \tabularnewline \cmidrule{1-1} {\small\texttt{array}} & {\small\texttt{rcrl}} & {\small\texttt{\&=\&}} & {\small\texttt{,\&(vv)}} & {\small\texttt{\textbackslash\textbackslash}}\tabularnewline \cmidrule{1-1} {\small\texttt{cases}} & \multirow{2}{*}{} & \multirow{2}{*}{{\small\texttt{=}}} & \multirow{2}{*}{{\small\texttt{,\textbackslash quad\textbackslash hfill(vv)}}} & \multirow{2}{*}{{\small\texttt{\textbackslash\textbackslash}}}\tabularnewline {\small\texttt{dcases}} & & & & \tabularnewline \bottomrule \end{tabular} \subsection{Settings for supplementary commands} In principle the settings \begin{verbatim} dbg, view, ^, xx, ff, 1s2, /min, /max, vv@, o, log, S+, S?, P+, P? \end{verbatim} are available for \verb`\nmcInfo`, \verb`\nmcMacros`, \verb`\nmcConstants`, \verb`\nmcReuse` but most will be of little relevance in most cases. \begin{itemize} \item \verb`\nmcInfo` \begin{itemize} \item \verb`view` equivalent to \verb`dbg=2`; \end{itemize} \item \verb`\nmcMacros` \begin{itemize} \item \verb`view` equivalent to \verb`dbg=2*3*5`; \item \verb`free` `deregister' a macro from \texttt{numerica}; \end{itemize} \item \verb`\nmcConstants` \begin{itemize} \item \verb`view` equivalent to \verb`dbg=2*3*5`; \item \verb`add` add the new list of constants to the current one; \end{itemize} \item \verb`\nmcReuse` \begin{itemize} \item \verb`view` equivalent to \verb`dbg=3`; \item \verb`save` the control sequence formed from the supplied name to the \verb`.nmc` file with the numerical result from the latest \verb`\eval` command and define it in \LaTeX ; \item \verb`renew` if necessary overwrite the value of a control sequence in the \verb`.nmc` file and redefine it in \LaTeX . \item \verb`load` load the saved control sequences and define them globally in \LaTeX ; \item \verb`delete` remove the listed control sequence and value from the \verb`.nmc` file and undefine it in \LaTeX ; \end{itemize} \end{itemize} \end{document}