Lacaml - Linear Algebra for OCaml

Overview

Lacaml is anOCaml library that interfaces with twopopular FORTRAN libraries, enabling developers to create high-performancenumerical applications requiring linear algebra. Ideal for researchers,engineers, and developers working on scientific computing and data analysis.

• BLAS: Basic Linear Algebra Subroutines
• LAPACK: Linear Algebra PACKage

Features

• BLAS/LAPACK are mature libraries, offering stability and performance.
• Lacaml interfaces with most BLAS/LAPACK functions, supporting linearequations, least squares, eigenvalue problems, SVD, Cholesky, QRfactorization, and more.
• Provides functions for easy matrix creation and manipulation.
• Offers powerful printing functions for large matrices, allowing users tospecify how much context to print.
• Integrates with the OCaml toplevel for easy experimentation and demonstration.
• Designed for efficiency and simplicity, with support for pre-allocated workarrays to optimize performance in iterative computations.
• Supports both 32-bit and 64-bit floating-point precision for real andcomplex numbers.
• Compatible with multithreaded programs, allowing concurrent execution.
• Function and argument names align with BLAS/LAPACK documentation forfamiliarity.
• OCaml manages most errors, with exceptions for illegal vector/matrix contents.

Usage

To use Lacaml, open the appropriate module for the desired precision andnumber type:

openLacaml.S(* Single-precision real numbers *)openLacaml.D(* Double-precision real numbers *)openLacaml.C(* Single-precision complex numbers *)openLacaml.Z(* Double-precision complex numbers *)

Link thelacaml library with your application. If not usingfindlib,also link thebigarray library.

TheLacaml.? modules offer the BLAS/LAPACK interface, withVec andMat submodules for vector and matrix operations.

Functions use optional arguments with defaults. For example:

letrank=gelssin_matout_matin(* `gelss` solves linear least squares problems *)...

To optimize, create work arrays outside loops:

letwork=gelss_min_work~m~n~nrhsinfori=1to1000doletrank=gelssin_mat~workout_matin...done

Access submatrices by specifying parameters likear andac for row andcolumn offsets, andm andn for the submatrix dimensions.

Printing

To print large matrices in the OCaml toplevel, you can use Lacaml’s printingfunctions. Here’s an example with a large random matrix:

##require"lacaml";;#openLacaml.D;;#letmat=Mat.random100200;;valmat:Lacaml.D.mat=C1C2C3C198C199C200R1-0.314362-0.5307110.309887...0.519965-0.2301560.0479154R20.8356580.5814040.161607...-0.749358-0.630019-0.858998R3-0.4034210.458116-0.497516...0.2108110.4220940.589661.....................R98-0.3524740.8788970.357842...0.150786-0.740110.353253R990.1048050.984924-0.319127...-0.143679-0.8582690.859059R1000.4199680.3333580.237761...-0.483535-0.02240160.513944

The output displays the corners of the matrix, with ellipses (...) foromitted parts. To reduce context further, useLacaml.Io.Toplevel.lsc tospecify the number of rows and columns to display:

#lsc2;;-:unit=()#mat;;-:Lacaml.D.mat=C1C2C199C200R1-0.314362-0.530711...-0.2301560.0479154R20.8356580.581404...-0.630019-0.858998...............R990.1048050.984924...-0.8582690.859059R1000.4199680.333358...-0.02240160.513944

For custom output, use theFormat module with Lacaml’s printing functions.Here’s an example with labels and custom settings:

openLacaml.DopenLacaml.Iolet()=letrows,cols=(200,100)inleta=Mat.randomrowscolsinFormat.printf"@[<2>This is an indented random matrix:@\n@\n%a@]@."(Lacaml.Io.pp_lfmat~row_labels:(Array.initrows(funi->Printf.sprintf"Row %d"(i+1)))~col_labels:(Array.initcols(funi->Printf.sprintf"Col %d"(i+1)))~vertical_context:(Some(Context.create2))~horizontal_context:(Some(Context.create3))~ellipsis:"*"~print_right:false~print_foot:false())a

This code might produce:

This is an indented random matrix:              Col 1     Col 2       Col 3      Col 98    Col 99   Col 100    Row 1  0.852078 -0.316723    0.195646 *  0.513697  0.656419  0.545189    Row 2 -0.606197  0.411059    0.158064 * -0.368989    0.2174    0.9001                  *         *           * *         *         *         *  Row 199 -0.684374 -0.939027 0.000699582 *  0.117598 -0.285587 -0.654935  Row 200  0.929341 -0.823264    0.895798 *  0.198334  0.725029 -0.621723

Lacaml provides options for customizing output, such as padding, numberformats, and precision.

Error Handling

Lacaml extensively checks arguments to ensure consistency with BLAS/LAPACKbut does not verify the contents of vectors and matrices. Checking forNaNs, infinities, or subnormal numbers in every matrix on each call iscomputationally expensive. Furthermore, some functions require matrices withspecific properties, like positive-definiteness, which are costly to verify.

BLAS/LAPACK may inconsistently handle degenerate shapes, such as emptymatrices or zero-sized operations. Detecting all corner cases and providingworkarounds is challenging.

Users should ensure that data passed to Lacaml functions is valid and avoidusing values with degenerate dimensions. User code should raise exceptionsfor suspicious values or explicitly handle unusual cases.

Supplementary Resources

API Documentation

The Lacaml API documentation is available both in the interface file andonline.

BLAS/LAPACK Man Pages

Unix systems typically include man pages for BLAS/LAPACK. For example,to learn about factorizing a positive-definite, complex, single-precisionmatrix, use:

man cpotrf

In Lacaml, this corresponds toLacaml.C.potrf. Further naming conventionsand documentation are available on the BLAS/LAPACK websites.

Examples

Theexamples directory contains demonstrations for linear algebra problemsusing Lacaml.

Performance Optimization

For optimal performance, install a BLAS variant optimized for your system.Processor vendors, such as Intel, offer highly optimized implementations. AppleincludesvecLib in itsAccelerate framework.

ATLAS is another efficient BLAS substitute,tailored to the architecture it compiles on. Linux users can find binarypackages from their distribution vendors, but recompilation may be necessaryfor optimal performance.

OpenBLAS is another alternative.

To use a non-standard library or location, set these environment variables:

• LACAML_CFLAGS for extra compilation flags.
• LACAML_LIBS to override default linking flags (-lblas and-llapack).

For CPU-specific optimization, use-march=native. In cloud environments,be cautious as VM changes might affect the CPU. The-ffast-math optioncan improve performance by allowing aggressive optimizations, but it mayalter standard floating-point behavior, potentially affecting numericalaccuracy and compliance with IEEE standards. Use with caution in applicationsrequiring precise numerical results. Generally,-O3 enhances performance,and Lacaml should perform well with these settings, potentially utilizingSIMD instructions.

Contact Information and Contributing

Report bugs, request features, or contribute via theGitHub issue tracker.

For the latest information, visit:https://mmottl.github.io/lacaml