Files in the top-level directory in any check-in

mathemaTcl
==========

dd. february 2017

Note:
The program make.tcl does not yet look for the --installdir option.

General
-------
mathemaTcl is a collection of Tcl extensions for numerical packages
written in C and Fortran, such as FFTW3 for fast Fourier transforms
and MINPACK to find the minimum of a function in one, two or more
variables. For some of these underlying packages the complete source
code is included, for others, notably the packages that have an
elaborate build procedure or consist of a vast amount of code, you
are expected to make the compiled libraries available for the platform
you want to use (parts of) mathemaTcl on.

For each package mathemaTcl provides "wrapper" code that makes it
possible to use the package from Tcl. For instance the routines found
in the SPECFUNC library that evaluates special mathematical functions
are exported to Tcl as ordinary commands:

The routine AIRYA in this library calculates the Airy Ai function as
well as the Airy Bi function and their first derivatives at a given
value of their argument. Within the wrapper this has been split up
into four commands: airyAi, airyBi, airyBiPrime and airyBiPrime,
residing in the ::Specfunc namespace.

In a similar way other functions and subroutines of this library have
been turned into Tcl commands. See the documentation per package for
details.

Note: the wrapper code has been generated using Wrapfort from the Ftcl
project (http://ftcl.sf.net).

Building
--------
The main purpose of mathemaTcl is to make the various packages
available for use in Tcl. To this end it comes with a simple program,
make.tcl, that builds the extensions. Its use is simple:

> tclsh make.tcl ?options?

Depending on the options, see below, it proceeds to:

   *  Identify the compiler suite/tool chain on the current platform -
      it requires a C compiler and for most packages also a Fortran
      compiler.
      The following compiler combinations are currently tried (in
      this order):
      - gcc and gfortran (Linux, Cygwin and MinGW)
      - gcc and Intel Fortran (useful on Linux for instance)
      - MicroSoft Visual C++ and Intel Fortran (useful on Windows)

      Note 1: there is no particular support for OSX, unfortunately
      Note 2: when you start the program, the environment must have
              been set up so that it can find the compilers.

   *  Create a small configuration file for use in the Makefiles per
      extension - this configuration file contains general macros such
      as the file extension for shared/dynamic libraries. Much of the
      information comes from the Tcl shell that you use, so there is
      no support for cross-compilation.

   *  Run the make utility for the platform to build the various
      extensions.

      Note 1: If there is no Fortran compiler, the extensions for
              Fortran-based libraries are not built.
      Note 2: Some extensions, like FFTW3 and LAPACK, require an
              extensive library. This library is searched for in a
              small set of standard locations. You can also put it in
              the subdirectory "libs-input" and the associated include
              files in the subdirectory "includes"

   * Install the extensions that have been successfully built. By
     default they are installed in the Tcl library subdirectory, but
     you can set a different location with the --installdir option.

The program takes the following sucommands and options:

  *  Without a subcommand it simply builds the extensions based on the
     compilers and libraries it finds.

  *  The "install" subcommand instructs it to install the extensions
     in the Tcl library directory or in a directory that you give
     explicitly.

  *  The option "--installdir dir" can be used to install the
     extensions in a specific location.

Libraries
---------
Most of the libraries that are wrapped by mathemaTcl are open source
libraries with a very permissive licence, very similar to Tcl itself.
However, there are exceptions:

  *  FFTW3 is licensed according to GPL2 (or later).

The original code for the libraries can be found mostly on Netlib
(http://www.netlib.org). In some cases the code has been modified
slightly, for instance in the case of GLOBAL, the write statements
have been disabled to avoid the routines to print the progress on
screen.

Related packages
----------------
In Tcllib (https://core.tcl.tk/tcllib) you will find the math modules,
which contains many mathematically oriented packages implemented in Tcl.

TclODE (http://tclode.sourceforge.net/) is a wrapper for the well-known
ODEPACK library. As the solution of (systems of) ordinary differential
equations is often done via implicit or semi-implicit methods, you may
need to provide a Jacobian matrix. The "symdiff" package in the Tcllib
math module provides procedures for symbolic differentation and can
construct a Jacobian automatically -
https://core.tcl.tk/tcllib/doc/trunk/embedded/www/tcllib/files/modules/math/symdiff.html

(More to follow ...)