chez-scmutils/README

# -*- 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 &centi &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.