%% 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[<options>]{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=<integer>` The rounding value. The value of \verb`<integer>`
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[<options>]{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[<options>]{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=<environment>`
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=<char>`. 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=<char>`. 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=<char>`
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}<x$ when $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=<char>` there (see §\ref{subsec:settingsMulti-formula-separator}),
where \verb`<char>` 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+=<integer>} \texttt{(P+=<integer>)\quad{}} \emph{additional}
rounding on top of the specified (or default) rounding for the calculation;
the larger \texttt{<integer>} is, the more likely that sum or product
has attained a stable value at the specified rounding value $r$;
default = $2$
\item \texttt{S?=<integer> $\ge0$ (P?=<integer> $\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}
    <pre-stuff>{\color{red}<red-stuff>}<post-stuff}
\end{verbatim}
but that is where the problem arises. `Unannounced' brace groups
(see §\ref{subsec:evalBraced-groups}) can easily result in unexpected
results or \LaTeX{} errors. Writing
\begin{centred}
\verb`\eval{$ \color{red} \sin \tfrac\pi6nT+1 $}[T=9,n=3]`$\Longrightarrow$
\eval{$ \color{red} \sin \tfrac\pi6nT+1 $}[T=9,n=3]
\end{centred}
is fine. So too, because the \verb`\color` command is `trapped'
within the braces defining the first argument of the \verb`\frac`,
is
\begin{centred}
\verb`\eval{$ \frac{\color[gray]{0.5}A}B $}[A=12,b=4]` $\Longrightarrow$\eval{$ \frac{\color[gray]{0.5}A}B $}[A=12,B=4].
\end{centred}
(Both arguments of the \verb`\color` command have been used for grayscale
output.) Also fine is
\begin{centred}
\verb`\eval{$ 3{\color{red}x}+1 $}[x=2]` $\Longrightarrow$ \eval{$ 3{\color{red}x}+1 $}[x=2]
\end{centred}
because juxtaposition in this case means multiplication, but substituting
the actual value \verb`2` for \verb`x` produces
\begin{centred}
\verb`\eval{$ 3{\color{red}2}+1 $}` $\Longrightarrow$ \eval{$ 3{\color{red}2}+1 $}.
\end{centred}
Recall the discussion at §\ref{subsec:evalBraced-groups}. An \emph{unannounced}
brace group is simply appended to what has gone before. The resulting
juxtaposition of $3$ and $x$ means multiply which was what was intended,
but the juxtaposition of $3$ and $2$ has quite a different meaning.

\subsection{\texttt{\textbackslash text}, \texttt{\textbackslash mbox} and
font commands}

\label{subsec:calcText-mbox-fonts}The content of a \verb`\text`
or \verb`\mbox` command is \emph{invisible} to the \verb`\eval`
command and is ignored in calculations,
\begin{centred}
\verb`\eval*{ 1/0.0123456789 \mbox{approx.\ 81} }[5]` $\Longrightarrow$
\eval*{ 1/0.0123456789 \mbox{approx.}}[5],
\end{centred}
even when the \verb`\text` or \verb`\mbox` contains mathematical
content. The author's view is that these commands are likely to be
used for comments, annotations, or remarks, rather than to modify
symbols of calculational significance.

Conversely, \emph{specific }font commands, like \verb`\mathbf` or
\verb`\textrm`, may well apply to such symbols and so there content
should be \emph{visible} to \verb`\eval`. This becomes useful should
numbers be input in scientific notation (see §\ref{subsec:settingsInputtingSciNotation})
where \verb`\textrm` or \verb`\texttt` may be useful so that a number
in scientific notation like \verb`2e-1` appearing in a formula or
the vv-list can display correctly rather than inappropriately as the
algebraic expression $2e-1$. 

The complete list of font commands where the content is visible to
\verb`\eval` is
\begin{enumerate}
\item \verb`\mathrm{}`, \verb`\mathit{}`, \verb`\mathtt{}`, \verb`\mathbf{}`,
\verb`\mathsf{}`, \verb`\mathcal{}`, \verb`\mathbb{}`, \verb`\mathfrak{}`,
\verb`\mathscr{}`
\item \verb`\textrm{}`, \verb`\textsf{}`, \verb`\texttt{}`, \verb`\textit{}`,
\verb`\textsl{}`, \verb`\textbf{}`, \verb`\textsc{}`
\end{enumerate}
The commands \verb`\mathbb{}` and \verb`\mathfrak{}` require the
\texttt{amsfonts} package to be loaded; \verb`\mathscr` requires
the \texttt{euscript} package to be loaded with the \verb`mathscr`
package option. 

\section{Environment precedence}

\label{sec:calcEnvironment-precedence}Math environments are relevant
particularly for multi-formula calculations. For a single formula
evaluation, either an inline (\verb`$`) or \verb`equation*` (\verb`\[`)
environment is probably all that is needed. 

The environment of a calculation is determined in one or two of three
ways: first, \verb`\eval` may sit within an environment, 
\begin{verbatim}
    \begin{env}
    \eval{...}
    \end{env}
\end{verbatim}
Second, the \verb`env` setting may be used, \verb`\eval[env=...]{...}`.
And third, \verb`\eval` may wrap around an environment, e.g. \verb`\eval{\[...\]}`.
Should a user, inadvertently or otherwise, specify `extra' environments
in a calculation, the environment wrapping around \verb`\eval` takes
precedence over the \verb`env`-setting environment which takes precedence
over the environment wrapped within \verb`\eval`:
\begin{centred}
\verb`$\eval[env=align,pp,ff]{\[ \pi,e,\phi,\gamma \]}[3]$` $\Longrightarrow$
$\eval[env=align,pp,ff]{\[ \pi,e,\phi,\gamma \]}[3]$.
\end{centred}
As you can see, the inline \verb`$` delimiters have prevails over
the \verb`align` environment and \verb`\[` \verb`\]` delimiters. 

Of course for the \verb`-ed` environments of \texttt{amsmath} a surrounding
math environment is necessary – as it is for \verb`cases`, \verb`dcases`
and \verb`array` environments. If \verb`\eval` wraps around an \verb`-ed`
or like environment, the surrounding environment may either be \verb`env`-specified
or wrap around \verb`\eval` (and if both are used, inadvertently
or otherwise, the latter takes precedence). 

\noindent{}%
\noindent\begin{minipage}[t]{1\columnwidth}%
\begin{shaded}%
Having these three different ways of specifying the environment may
seem like overkill, but they are likely to arise in different contexts.
The author envisaged a user writing an expression within an environment
and then wondering what it evaluates to. Surely it is natural in this
case just to wrap \verb`\eval` around the lot, environment and expression,
and let \emph{it}, \verb`\eval`, do the \emph{formula=result} typesetting.
Or, one may enter an expression into \verb`\eval` \emph{before} deciding
on the environment. How much easier just to write \verb`env=align*`
(or whatever the environment chosen is) in the settings option than
to insert \verb`\begin{align*}` before the expression and \verb`\end{align*}`
after. Finally, \verb`\eval` can find itself within a surrounding
environment in many ways. It may be necessary in order to use an AMS
\verb`-ed` environment, or it may occur in a context like that in
§\ref{subsec:introExploring}. The upshot is that all three ways of
specifying environments should be – and are – catered for as of version
3.0.0.\end{shaded}%
\end{minipage}

\chapter{Error messages }

\label{chap:errorsErrors}There are two kinds of error in \texttt{numerica}:
those in the underlying \LaTeX{} which are reported in the \LaTeX{}
log and shown on the terminal, and generally halt compilation, and
specifically \texttt{numerica}-related errors which do not halt compilation
and produce messages displayed in the pdf where one would expect the
result of the calculation to be. The original reason for doing things
this way was to enable \texttt{numerica} to be used effectively with
the instant preview facility of the document processor \LyX . More
philosophically, one might view such errors as similar to errors of
grammar or spelling mistakes in text. It is not clear that they should
halt compilation. 

Hence strictly \texttt{numerica}-related errors leave brief messages
in the pdf at the offending places. From version 3.0.0 of \texttt{numerica}
they also leave messages in the \LaTeX{} log like
\begin{centred}
\verb`numerica error on line <n> in <location>`
\end{centred}
where \verb`<location>` will usually be \verb`formula` or \verb`variable=value list`
or possibly some more specific location like \verb`sum` or \verb`product`.
\verb`<n>` 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 = <integer>
\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}
    ^ = <char>
\end{verbatim}
\noindent in the settings option, where \verb`<char>` 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 = <integer>
\end{verbatim}
into the settings option. If \verb`<integer>` is \verb`0`, the check
for (and conversion of) multi-token variables is turned off; if \verb`<integer>`
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 = <char>
\end{verbatim}
in the settings option means multiple formulas separated by \verb`<char>`
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`= <char>` 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 = <integer1>
    /max = <integer2>
\end{verbatim}
(Those are \emph{not} backslashes!) \verb`<integer1>` 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@ = <integer>
\end{verbatim}
or (as in version 1 of \texttt{numerica}),
\begin{verbatim}
    vvmode = <integer>
\end{verbatim}
in the settings option it is possible to turn on or off the ability
to repeatedly evaluate the vv-list; \verb`<integer>` 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 = <positive number>
\end{verbatim}
where \verb`<positive number>`~$\ne1$ to the settings option of
the \verb`\eval` command. The \verb`<positive number>` 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+=<integer>`, \verb`P+=<integer>`, \verb`S?=<integer>`,
\verb`P?=<integer>`, 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=<environment>
\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=<char(s)>
\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=<tokens>
\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 = <tokens>
\end{verbatim}
where \verb`<tokens>` 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 = <char(s)> 
\end{verbatim}
places {\ttfamily\verb`<char(s)>`} 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`<char(s)>`} 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 = <char(s)>
\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}
    \} = <space-spec><right-delimiter>
\end{verbatim}
Here \verb`<space-spec>` is either a single token or a brace group
defining a space between the numerical results and the right delimiter.
\verb`<right-delimiter>` 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<cmd>*[settings]{main arg}[vv-list][rounding]`
\end{centred}
where \verb`<cmd>` 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{<arg>} 
\end{verbatim}
(or, using the short-name form, \verb`\info{<arg>}`) where, at this
stage, \verb`<arg>` 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=<integer>`
(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=<char>` 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=<char>`,
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 {<result>}`, 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`<result>`.
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 {<result>}` and globally defines \verb`\foo` to expand
to \verb`<result>`.
\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 {<result>}`;\verb`\foo`
is globally defined to expand to \verb`<result>`; 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 {<result>}`,
if necessary overwriting any previously saved value for \verb`\foo`;
\verb`\foo` is globally defined to expand to \verb`<result>`; 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{<stuff>}\right)\mathtt{<more\ stuff>}
\]
 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}
    <stuff>
    \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}
    <preamble>
    \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 <your
name>\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<preamble>
\begin{verbatim}
    <preamble>
    \begin{document}
    \begin{preview}
    <stuff>
    \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=<char(s)>` 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}
