chez-scmutils

# -*- mode: org -*-

* Description

This is a port of the 'MIT Scmutils' library to Chez Scheme. On top
of providing a set of of procedures for numerical computations, the
library provides a set of generic operators extending many
mathematical functions and operators to work with
- symbolic values,
- vectors, matrices and structures (to represent, e.g., tensors)
- physical quantities (values with units),
- ...

** Examples

Load the libraries in the REPL (see below for further details):
#+BEGIN_SRC scheme
(import (scmutils base)
(scmutils generic)
(scmutils calculus))
(start-scmutils-print!)
#+END_SRC

You can compute the derivative of a scalar or vector valued
function evaluated at point 'x with:
#+BEGIN_SRC scheme
((D (up cos sin)) 'x)
#+END_SRC
where 'up' denotes a contravariant vector which is represented by
a Scheme vector and 'D' is the generic derivative operator.

The operator 'D' is also used to compute the gradient of functions
of multiple arguments:
#+BEGIN_SRC scheme
(define (g x y)
(sin (* x y)))
((D g) 'x0 'y0)
#+END_SRC
The result is a 'down' tuple' representing a covariant vector which
can be contracted with a contravariant vector to obtain the
approximate change in the function 'g':
#+BEGIN_SRC scheme
(* ((D g) 'x0 'y0)
(up 'dx 'dy))
#+END_SRC

You can work with 'structures' (see refman) and with matrices:
#+BEGIN_SRC scheme
(let ((M (matrix-by-rows (list 'a 0) (list 0 'b))))
(determinant M))
#+END_SRC

For numerical computations the library includes procedures to solve
differential equations, doing numerical integration, root finding
and single- and multi-variable minimization among other things:
#+BEGIN_SRC scheme
(minimize (square cos) 0 :pi)
#+END_SRC

You can work with units as well:
#+BEGIN_SRC scheme
(/ (& 30 ¢i &meter) :c)
#+END_SRC
with ':c' the speed of light in m/s (one of several built-in
constants).

* Build

To build the libraries run "make". By default it looks for a Chez
Scheme binary called "chez-scheme". If the name of your binary is
different, you can specify it as follows (for all targets):

make CHEZ=my-chez-scheme-bin

* Install

By default "make install" will install the libraries under the
prefix "/usr/local". You can specify a different installation
prefix directory as follows:

make install PREFIX=/my-prefix/path

This will install all compiled libraries (*.so files) to
$PREFIX/lib/csvX.Y-site, where X.Y is Chez's version. If in
addition you want to install the source files, use the 'install-src'
target. They are installed in the same directory as the .so files.

* Use

The library consists of the following sub-libraries:

- (scmutils base): defines the fundamental part of the library.
Currently we export most defined functions, even many internal
ones. In the future we may clean up the list of exported
symbols.

- (scmutils generic): exports the generic operators such as '+',
'*', ... with names equal to standard Scheme procedures.

- (scmutils mechanics): exports the functions described in the book
'Structure and Interpretation of Classical Mechanics' by
G. J. Sussman and J. Wisdom.

Note that, because Chez Scheme doesn't provide a built-in
graphics library, the plotting functions described in the book
are not available. As an alternative, interfacing with 'Gnuplot'
from Chez Scheme is pretty straight-forward.

- (scmutils calculus): exports the functions described in the book
'Functional Differential Geometry' by G. J. Sussman and
J. Wisdom.

Note that the (scmutils mechanics) library defines a version of
'Lie-derivative' which is less general than the one defined in
(scmutils calculus). Be sure to use the latter for calculus
purposes.

If you want to load everything you can just import all of above
libraries in the indicated order, making sure to import
'Lie-derivative' from (scmutils calculus) and not from (scmutils
mechanis).

Scmutils includes a custom REPL to drop internal tag information.
To start it execute (start-scmutils-print!), to stop it use
(stop-scmutils-print!). The custom REPL automatically simplify
expression results before printing them.

Once the custom REPL is active and if you have LaTeX installed, the
result of the last expression can be nicely displayed with the full
mathematical formatting capability of LaTeX with the command '(de)'.

The original MIT/GNU Scheme Scmutils includes several global
variables, usually identified by names starting and ending with
'*'. Because the R6RS Scheme standard doesn't allow libraries to
export mutable variables, we changed most of them to 'parameters'.

* Limitations

MIT/GNU Scheme has a very powerful condition system, including the
'restart' feature found in Common-Lisp. This allows one to extend
Scheme without having to implement a new interpreter. This feature
is used in Scmutils to allows, e.g., a vector of functions in
operator position.

The condition system of R6RS Scheme is more limited and doesn't
provide 'restarts'. As a consequence, sometimes one has to
explicitly use the generic version of 'apply', called 'g:apply',
instead of the Scheme native one. As an example, the following
code produces an error of type "attempt to apply non-procedure":

#+BEGIN_SRC scheme
(((d (literal-manifold-function 'f-rect R2-rect))
(coordinate-system->vector-basis R2-rect))
((point R2-rect) (up 'x0 'y0)))
#+END_SRC

To fix the problem one has to explicitly use 'g:apply' as shown
below:

#+BEGIN_SRC scheme
(g:apply
((d (literal-manifold-function 'f-rect R2-rect))
(coordinate-system->vector-basis R2-rect))
(list ((point R2-rect) (up 'x0 'y0))))
#+END_SRC

This should only be necessary in code that you type at the REPL or
in user defined functions.