Emacs philosophy usually leads to implement core functions not related to text processing in specialized external programs, and then use Elisp to provide an Emacs interface to those programs. As an advantage, the core software is not specific to Emacs (that is the case for Elisp programs) and can be used in other contexts.

However, it may be convenient to implement a few simple
numerical computations directly in Elisp, rather than always
interfacing it with external programs. Being Elisp
mathematical library rather limited, a more comprehensive
numerical library is welcome. Fortunately, Emacs incorporates
Calc, an algebra system written in Elisp. Calc is a program
mainly meant to
be called
from Emacs, rather than a proper numerical
library. However, a simple interface to Calc from other Elisp
code is provided by the nice function *calc-eval*. Here
we show its usage through a couple of examples.

For a complete guide to Calc see
the official
documentation (the source code is under-documented, don't
waste time on that and refer to the manual instead), in
particular the section about how to
call Calc
from other Lisp programs. The following code has been
tested with GNU Emacs 24.5.1 and *calc-eval* is already
on the list of recommended autoload functions, so no special
preparations are needed to load Calc before
calling *calc-eval*.

On this page: |

If you are reading this, chances are that you are already familiar with Elisp. If not, let's recall that Elisp (Emacs Lisp) is a dialect of the Lisp language family. It was designed as the extension language for the Emacs text editor. As such, its main focus is string manipulation and representation on screen. Despite more than 30 years of development, there seems to be no library dedicated to numerical computing in Elisp. Indeed, this is not why Elisp was created. Heavy computations may stuck Emacs, hence the full development environment at once.

Elisp code is composed by symbolic expressions enclosed by parenthesis and can be evaluated as follows. Copy the text on this page and paste it into Emacs. Place the cursor at the end of code parenthesis and press the key strokes `C-x C-e' (where C is the Ctrl key). For example:

(+ 1 1) <= cursor here, press C-x C-e

The result of the evaluation will be displayed in the Emacs mini-buffer. If anything goes wrong and you are stuck in some buffer without knowing what to do, press the key combination `C-g'.

See also An Introduction to Programming in Emacs Lisp for a gentle initiation to Elisp (and to programming in general).

First, to avoid bugs it is useful to point out that Calc
gives to division a lower precedence than
multiplication. Hence the algebraic expression *1 / 2 *
3* is interpreted as *1 / (2 * 3)*, not as *(1 / 2)
* 3* as it may be commonly expected. Apart from this
convention, Calc algebraic expressions are fairly
intuitive. The simplest usage of *calc-eval* is
illustrated by the following call.

```
(calc-eval "1+1")
;; => "2"
```

Of course, the example above has no practical advantage over
evaluating directly *(+ 1 1)*. The advantage
of *calc-eval* is that it allows to access several
functions defined in Calc and not in the Elisp mathematical
library. For instance, this is the case for hyperbolic
functions. They can computed from scratch given the
exponential function of Elisp mathematical library (or
possibly using approximations or asymptotic forms depending on
the value of the argument). Alternatively, they can easily be
accessed from the Calc interface. Let's consider the
hyperbolic sine *sinh(x)*.

```
(calc-eval "sinh(0.5)")
;; => "0.521095305494"
```

Arguments can be passed separately using the
placeholders *$*, *$$*, ... for the
first, second and so on argument. In the following *nil*
is a separator and in general it can be replaced by a symbol
triggering some option (see later).

```
(calc-eval "sinh($)" nil "0.5")
;; => "0.521095305494"
```

The previous calls are easy to use but inefficient, because
they needs to convert strings to numbers. Passing a Calc data
structure is more efficient, but cumbersome. For instance, the
float `0.5' must be passed in a list separating mantissa and
exponent `(float 5 -1)', see the section
about data
type formats of Calc manual. That's often too ugly, see
the example below to compute once again *sinh(0.5)*, but
passing a raw Calc data structure with the *raw* symbol.

```
(calc-eval "sinh($)" 'raw '(float 5 -1))
;; => (float 521095305494 -12)
```

In this case it is more convenient to call directly Calc
internal
functions. Calc manual states that those functions
starting by *calcFunc-* are also meant to be called from
other programs.

```
(calcFunc-sinh '(float 5 -1))
;; => (float 521095305494 -12)
```

However, internal functions are not always intuitive to use (see the next example) and the source code lacks of documentation.

The list of
Calc internal
functions mentions *ninteg* for numerical
integration. The respective internal function callable from
external Elisp program is
then *calcFunc-ninteg*. However, its use is not
documented. Inspection of source code suggests that an
expression formatted according to Calc raw format should be
given as an argument, which is not trivial. Here the
function *calc-eval* is then especially useful, since it
allows the use of *ninteg* through more intuitive
expressions. The use of *ninteg* is documented in a
solution of the a Calc programming tutorial
exercise.
Let's integrate *sin(x)/x* from 0 to 1.

```
(calc-eval "ninteg(sin(x)/x, x, 0, 1)")
;; => "0.0174529971573"
```

Now let's look at further options associated
to *calc-eval*. As already seen, an argument list can be
passed separately using the
placeholders *$*, *$$*, ... .

```
(calc-eval "ninteg($, $$, $$$, $$$$)" nil "sin(x)/x" "x" "0" "1")
;; => "0.0174529971573"
```

Numerical integration is of course faster if the default precision (12 digits) is reduced to, say, 6 digits.

```
(calc-eval '("ninteg(sin(x)/x, x, 0, 1)" calc-internal-prec 6))
;; => "0.017453"
```

If the integral cannot be evaluated a symbolic expression is
returned. For instance, if a large upper integration limit is
required, e.g., *ninteg(sin(x)/x, x, 0, 10000)*, the
integral may fail to converge (this is the case with default
12 digits precision). Let's look also at another
straightforward example independent from the
precision. The manual
states that quadrature is performed with the open Romberg
method, so that it is safe to integrate *sin(x)/x* from
zero, as shown above. However, integration across
singularities is not supported. For instance, the integral
of *1/sqrt(x)* from 0 to 1 should give 2.

```
(calc-eval "ninteg(1/sqrt(x), x, 0, 1)")
;; => "ninteg(1 / sqrt(x), x, 0, 1)"
```

The numerical integral could not be evaluated, and the formal
integral is returned back. When performing numerical
integration in Elisp, however, it is often better to rise an
error if an integral fails to converge instead of returning a
formal expression. The option *num* specifies that we
expect to operate with numbers, and rises an error if this is
not the case.

```
(calc-eval "ninteg(1/sqrt(x), x, 0, 1)" 'num)
;; => (0 "Integral failed to converge")
```

Depending on the application it may be better to rise a
standard Elisp error instead. This can also be done. Setting
the variable *calc-eval-error* to *t*, Calc calls
the standard Elisp error function. To avoid conflicts with
other programs, it is good practice to set the variable in a
local scope through a *let* statement, and not globally
through *setq*.

```
(let ((calc-eval-error t))
(calc-eval "ninteg(1/sqrt(x), x, 0, 1)" 'num))
;; => Debugger entered--Lisp error: (error "Integral failed to converge")
;; ...
```

Finally, let's combine some of the options illustrated above
to integrate *sin(x)/x* from 0 to 1.

```
(let ((calc-eval-error t))
(calc-eval '("ninteg(sin(x)/x, x, $, $$)" calc-internal-prec 6)
'num "0" "1"))
;; => "0.017453"
```

Reading the previous expression from the inner parenthesis to
the outer one, we first set 6 digit precision and define the
algebraic expression for the integral. The list is passed to
*calc-eval*. The integration boundaries are set
separately (corresponding to the place holders $ and
$$), after the separator *num* that tells Calc to
return an error in case non-numerical expressions are
encountered. Finally, thanks to the outer *let*
statement, if an error is found the standard Elisp error
function is called, instead of the one from Calc.

The function *calc-eval* provides a fairly intuitive
interface to Calc functions library and it can be easily
integrated in Elisp programs. Since it requires strings
conversion to numbers, the solution is not optimal in terms of
performance and it should only be used for simple
computations. Calling directly Calc internal functions is more
efficient but too cumbersome. Implementing algorithms from
scratch may be a better option.

As a benchmark, we measured (on an Intel Core i7-2620M CPU
@ 2.70GHz) the time necessary to evaluate *sinh(0.5)*:

- Using the
*calc-eval*interface: 0.361457 s. - Using he
*calcFunc-sinh*internal function : 0.000267 s. - Implementing
*sinh*from scratch based on the exponential function from Elisp math library: 0.000012 s.

Hence, implementing the function from scratch provides faster
results by a factor 10 compared to Calc internal function, and
by a factor 10^{4} compared to the *calc-eval*
interface. Furthermore, while the implementation from scratch
requires about the same time for much larger or smaller
arguments, Calc functions result in significantly slower
results. Clearly, the Calc interface should be used only if
efficiency is not an issue.

On the other hand, Elisp itself is not the optimal language
for non-trivial numerical computations. Other programs with
optimized numerical libraries may also provide Elisp
interfaces (it may be worth to check if this is the case for
Octave or Maxima), but it requires the installation of further
components (instead, Calc is already included in recent enough
Emacs versions). If time-consuming algorithms are required it
is advisable to implement them with external programs. Elisp
can then be used, for instance, to read a result printed on
stdout and format it in a Emacs buffer. Several tools are
provided in Elisp standard library for that. For instance, the
following line displays in Emacs mini-buffer the output of the
shell command *echo "4+10" | bc* (that
calculates the sum with the *bc* program). Any program
callable from command line can be used in a similar way.

```
(shell-command-to-string "echo \"4+10\" | bc")
;; => "14"
```

Happy hacking!