lacaml / README.txt


                         Distribution of "LACAML"



                               BLAS, LAPACK

                         THE DISTRIBUTED MAKEFILES


                   Files in this distribution

AUTHORS              - Authors of Lacaml.

Changes              - History of code changes.

INSTALL              - Short notes on compiling and installing the library


Makefile             - Global Makefile

OCamlMakefile        - Makefile for easy handling of compilation of not
                       so easy OCaml-projects.  It generates dependencies
                       of OCaml-files automatically, is able to handle
                       "ocamllex"-, "ocamlyacc"-, IDL- and C-files and
                       generates native- or byte-code, as executable or
                       as library - with thread-support if you want!

README.txt           - This file

examples/            - Various linear algebra examples.

lib/          - The global interface to LACAML, which collects
                       modules for real and complex transforms in single
                       or double precision.

lib/        - Globally visible utility-functions and definitions.

lib/float32.mli      - Modules that specialize for real/complex and
lib/         single/double precision (globally visible through

lib/impl_SDCZ.mli    - These implement the OCaml-interface to BLAS (or
lib/       its more efficient ATLAS-implementation) and
lib/impl_SD.mli        LAPACK and only look like valid OCaml-files. In
lib/         fact four modules are generated from the SDCZ-files:
lib/impl_CZ.mli        two for single-precision operations, another
lib/         two for double-precision, for real and complex
                       transforms respectively. The SD- and CZ-files handle
                       special functions that are only available for either
                       real or complex transformations.

lib/impl_SDCZ_c.c    - The C-interface to BLAS and LAPACK that works as a
lib/impl_SD_c.c        wrapper for the OCaml-interface, which cannot
lib/impl_CZ_c.c        interface FORTRAN directly.

lib/vec_SDCZ.mli     - Implementation of commonly useful vector operations.

lib/fold_col.c       - These C-files contain generic implementations of
lib/fold2_col.c        vector functions. They can be parameterized with
lib/vec_combine.c      macros for special cases.

lib/mat_SDCZ.mli     - Implementation of commonly useful matrix operations.

lib/         - Internal auxiliary functions needed by other modules.

lib/impl_c.c         - Auxiliary C-routines needed in the C-interface.

lib/lacaml_macros.h  - C-header with macro definitions for writing
                       precision independent and convenient interfaces
                       to FORTRAN-libraries.

lib/myXerbla.f       - Dummy FORTRAN module for error handling that
                       overrides the one provided with BLAS and LAPACK:
                       these would otherwise abort execution of programs
                       on errors. Now we can handle errors in OCaml


                                 What is it?

This OCaml-library interfaces the BLAS-library (Basic Linear Algebra
Subroutines) and LAPACK-library (Linear Algebra routines), which are
written in FORTRAN.

This allows people to write high-performance numerical code for
applications that need linear algebra.


                            Why should you use it?

Here is a list of features:

  * The BLAS- and LAPACK-libraries have evolved over about two decades
    of time and are therefore extremely mature both in terms of stability
    and efficiency.

  * The OCaml-interface was designed in a way to combine both the
    possibility of gaining optimum efficiency (e.g. by allowing the
    creation of work arrays outside of loops) with simplicity (thanks
    to labels and default arguments).

  * The code is precision-independent and supports both real and complex
    transforms in a consistent way. There are four modules that
    implement exactly the same interface modulo the precision type and
    real/complex numbers/transforms. If you refer to elements in this
    interface only, your code becomes precision- and (if meaningful)
    real/complex independent, too: you can choose at anytime whether
    you want to use single-precision or double-precision simply by
    "open"ing the required module.

  * You can fully exploit the library within multithreaded programs: most
    numerical routines are likely to run for a long time, but they will
    never block other threads. This also means that you can execute
    several routines at the same time on several processors if you use
    native threads.

  * To make things easy for people used to the "real" implementation
    in FORTRAN but also for beginners who need detailed documentation,
    both function- and argument names have been kept compatible to the
    ones used in the BLAS- and LAPACK-documentation. Only exception: you
    need not prefix functions with "s", "d", "c" or "z" to indicate the
    precision and type of numbers, because OCaml gives us more powerful
    means to choose them.


                          General Usage Information

You can make use of this library by referring to the corresponding module you
need for your precision and number type:

  open Lacaml.Impl.S
  open Lacaml.Impl.D
  open Lacaml.Impl.C
  open Lacaml.Impl.Z

These modules become available if you link against the "lacaml"-library,
which is produced by this distribution. You also need to link against
the "bigarray"-library provided by the OCaml-distribution and do not use
findlib to resolve dependencies automatically. The "Lacaml.Impl.?"-modules
implement the BLAS/LAPACK-interface, and their corresponding submodules
"Vec" and "Mat" provide for vector and matrix operations that relate to
the given precision and number type.

Most functions allow optional arguments (= default arguments). If you
do not provide them at the call-site, sane defaults will be used instead.

Convenient way of calling a function, e.g.:

  let rank = gelss in_mat out_mat in ...

This would perform computation of the solution to a general least squares
problem (= linear regression) with the SVD-algorithm using "in_mat"
as the matrix containing the predictor variables and "out_mat" as the
matrix containing (possibly many) response variables (this function can
handle several response variables at once).  The result is the rank of
the matrix, the matrices provided in the arguments will be overwritten
with further results (here: the singular vectors and the solution matrix).

If the above happened in a loop, this would be inefficient, because a
work-array would have to be allocated (and later deallocated) at each
call. You can hoist the creation of this array out of the loop:

Efficient way of calling a function, e.g. (m, n, nrhs are problem
dependent parameters):

  let work = gelss_min_work ~m ~n ~nrhs in
  for i = 1 to 1000 do
    let rank = gelss in_mat ~work out_mat

Take a look at files "impl_SDCZ.mli", "impl_SD.mli", ... etc., to see,
which ways exists to pass parameters and to learn about the defaults.

All matrices can be accessed in a restricted way, i.e. you can specify
submatrices for all matrix parameters. E.g. if some matrix is called "a"
in the interface documentation, you can specify the left upper corner of
the wanted submatrix for the operation by setting "ar" for the row and
"ac" for the column (1 by default). A vector "y" would have an extra
optional parameter "ofsy" (also 1 by default).


Up-to-date information (newest release of distribution) can always be
found at:

BLAS and LAPACK (distribution, documentation) can be found at:

ATLAS, a very efficient and compatible substitute for BLAS, it specializes
code for specific architectures, can be found here:

Binary packages (e.g. RPMs) for Linux should be available from your
distribution vendor's site.



New York, 2008-01-02
Markus Mottl

Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.