{"id":15470468,"url":"https://github.com/mmottl/lacaml","last_synced_at":"2025-10-19T20:23:38.468Z","repository":{"id":18248491,"uuid":"21401121","full_name":"mmottl/lacaml","owner":"mmottl","description":"OCaml bindings for BLAS/LAPACK (high-performance linear algebra Fortran libraries)","archived":false,"fork":false,"pushed_at":"2025-01-19T17:23:05.000Z","size":3655,"stargazers_count":128,"open_issues_count":1,"forks_count":16,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-29T01:12:31.782Z","etag":null,"topics":["blas","lapack","linear-algebra","matrix","ocaml","vector"],"latest_commit_sha":null,"homepage":null,"language":"OCaml","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mmottl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-07-01T20:13:59.000Z","updated_at":"2025-03-21T17:12:59.000Z","dependencies_parsed_at":"2023-01-16T21:45:42.203Z","dependency_job_id":"908e1e2d-1064-4902-b804-6402c940a608","html_url":"https://github.com/mmottl/lacaml","commit_stats":{"total_commits":585,"total_committers":14,"mean_commits":"41.785714285714285","dds":0.2205128205128205,"last_synced_commit":"1175b1533de0f0a6c99fb8a073455127c6c280b2"},"previous_names":[],"tags_count":97,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmottl%2Flacaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmottl%2Flacaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmottl%2Flacaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mmottl%2Flacaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mmottl","download_url":"https://codeload.github.com/mmottl/lacaml/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247276164,"owners_count":20912288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blas","lapack","linear-algebra","matrix","ocaml","vector"],"created_at":"2024-10-02T02:04:50.642Z","updated_at":"2025-10-19T20:23:38.204Z","avatar_url":"https://github.com/mmottl.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Lacaml - Linear Algebra for OCaml\n\n## Overview\n\nLacaml is an [OCaml](http://www.ocaml.org) library that interfaces with two\npopular FORTRAN libraries, enabling developers to create high-performance\nnumerical applications requiring linear algebra. Ideal for researchers,\nengineers, and developers working on scientific computing and data analysis.\n\n- [BLAS](http://www.netlib.org/blas): Basic Linear Algebra Subroutines\n- [LAPACK](http://www.netlib.org/lapack): Linear Algebra PACKage\n\n## Features\n\n- BLAS/LAPACK are mature libraries, offering stability and performance.\n- Lacaml interfaces with most BLAS/LAPACK functions, supporting linear\n  equations, least squares, eigenvalue problems, SVD, Cholesky, QR\n  factorization, and more.\n- Provides functions for easy matrix creation and manipulation.\n- Offers powerful printing functions for large matrices, allowing users to\n  specify how much context to print.\n- Integrates with the OCaml toplevel for easy experimentation and demonstration.\n- Designed for efficiency and simplicity, with support for pre-allocated work\n  arrays to optimize performance in iterative computations.\n- Supports both 32-bit and 64-bit floating-point precision for real and\n  complex numbers.\n- Compatible with multithreaded programs, allowing concurrent execution.\n- Function and argument names align with BLAS/LAPACK documentation for\n  familiarity.\n- OCaml manages most errors, with exceptions for illegal vector/matrix contents.\n\n## Usage\n\nTo use Lacaml, open the appropriate module for the desired precision and\nnumber type:\n\n```ocaml\nopen Lacaml.S  (* Single-precision real numbers *)\nopen Lacaml.D  (* Double-precision real numbers *)\nopen Lacaml.C  (* Single-precision complex numbers *)\nopen Lacaml.Z  (* Double-precision complex numbers *)\n```\n\nLink the `lacaml` library with your application. If not using `findlib`,\nalso link the `bigarray` library.\n\nThe `Lacaml.?` modules offer the BLAS/LAPACK interface, with `Vec` and\n`Mat` submodules for vector and matrix operations.\n\nFunctions use optional arguments with defaults. For example:\n\n```ocaml\nlet rank = gelss in_mat out_mat in\n(* `gelss` solves linear least squares problems *)\n...\n```\n\nTo optimize, create work arrays outside loops:\n\n```ocaml\nlet work = gelss_min_work ~m ~n ~nrhs in\nfor i = 1 to 1000 do\n  let rank = gelss in_mat ~work out_mat in\n  ...\ndone\n```\n\nAccess submatrices by specifying parameters like `ar` and `ac` for row and\ncolumn offsets, and `m` and `n` for the submatrix dimensions.\n\n### Printing\n\nTo print large matrices in the OCaml toplevel, you can use Lacaml's printing\nfunctions. Here's an example with a large random matrix:\n\n```ocaml\n# #require \"lacaml\";;\n# open Lacaml.D;;\n# let mat = Mat.random 100 200;;\nval mat : Lacaml.D.mat =\n              C1        C2        C3          C198       C199      C200\n    R1 -0.314362 -0.530711  0.309887 ...  0.519965  -0.230156 0.0479154\n    R2  0.835658  0.581404  0.161607 ... -0.749358  -0.630019 -0.858998\n    R3 -0.403421  0.458116 -0.497516 ...  0.210811   0.422094  0.589661\n             ...       ...       ... ...       ...        ...       ...\n   R98 -0.352474  0.878897  0.357842 ...  0.150786   -0.74011  0.353253\n   R99  0.104805  0.984924 -0.319127 ... -0.143679  -0.858269  0.859059\n  R100  0.419968  0.333358  0.237761 ... -0.483535 -0.0224016  0.513944\n```\n\nThe output displays the corners of the matrix, with ellipses (`...`) for\nomitted parts. To reduce context further, use `Lacaml.Io.Toplevel.lsc` to\nspecify the number of rows and columns to display:\n\n```ocaml\n# lsc 2;;\n- : unit = ()\n# mat;;\n- : Lacaml.D.mat =\n            C1        C2           C199      C200\n  R1 -0.314362 -0.530711 ...  -0.230156 0.0479154\n  R2  0.835658  0.581404 ...  -0.630019 -0.858998\n           ...       ... ...        ...       ...\n R99  0.104805  0.984924 ...  -0.858269  0.859059\nR100  0.419968  0.333358 ... -0.0224016  0.513944\n```\n\nFor custom output, use the `Format` module with Lacaml's printing functions.\nHere's an example with labels and custom settings:\n\n```ocaml\nopen Lacaml.D\nopen Lacaml.Io\n\nlet () =\n  let rows, cols = (200, 100) in\n  let a = Mat.random rows cols in\n  Format.printf \"@[\u003c2\u003eThis is an indented random matrix:@\\n@\\n%a@]@.\"\n    (Lacaml.Io.pp_lfmat\n       ~row_labels:(Array.init rows (fun i -\u003e Printf.sprintf \"Row %d\" (i + 1)))\n       ~col_labels:(Array.init cols (fun i -\u003e Printf.sprintf \"Col %d\" (i + 1)))\n       ~vertical_context:(Some (Context.create 2))\n       ~horizontal_context:(Some (Context.create 3))\n       ~ellipsis:\"*\" ~print_right:false ~print_foot:false ())\n    a\n```\n\nThis code might produce:\n\n```text\nThis is an indented random matrix:\n\n              Col 1     Col 2       Col 3      Col 98    Col 99   Col 100\n    Row 1  0.852078 -0.316723    0.195646 *  0.513697  0.656419  0.545189\n    Row 2 -0.606197  0.411059    0.158064 * -0.368989    0.2174    0.9001\n                  *         *           * *         *         *         *\n  Row 199 -0.684374 -0.939027 0.000699582 *  0.117598 -0.285587 -0.654935\n  Row 200  0.929341 -0.823264    0.895798 *  0.198334  0.725029 -0.621723\n```\n\nLacaml provides options for customizing output, such as padding, number\nformats, and precision.\n\n### Error Handling\n\nLacaml extensively checks arguments to ensure consistency with BLAS/LAPACK\nbut does not verify the contents of vectors and matrices. Checking for\nNaNs, infinities, or subnormal numbers in every matrix on each call is\ncomputationally expensive. Furthermore, some functions require matrices with\nspecific properties, like positive-definiteness, which are costly to verify.\n\nBLAS/LAPACK may inconsistently handle degenerate shapes, such as empty\nmatrices or zero-sized operations. Detecting all corner cases and providing\nworkarounds is challenging.\n\nUsers should ensure that data passed to Lacaml functions is valid and avoid\nusing values with degenerate dimensions. User code should raise exceptions\nfor suspicious values or explicitly handle unusual cases.\n\n### Supplementary Resources\n\n#### API Documentation\n\nThe Lacaml API documentation is available both in the interface file and\n[online](http://mmottl.github.io/lacaml/api/lacaml).\n\n#### BLAS/LAPACK Man Pages\n\nUnix systems typically include man pages for BLAS/LAPACK. For example,\nto learn about factorizing a positive-definite, complex, single-precision\nmatrix, use:\n\n```sh\nman cpotrf\n```\n\nIn Lacaml, this corresponds to `Lacaml.C.potrf`. Further naming conventions\nand documentation are available on the BLAS/LAPACK websites.\n\n#### Examples\n\nThe `examples` directory contains demonstrations for linear algebra problems\nusing Lacaml.\n\n## Performance Optimization\n\nFor optimal performance, install a BLAS variant optimized for your system.\nProcessor vendors, such as Intel, offer highly optimized implementations. Apple\nincludes `vecLib` in its `Accelerate` framework.\n\n[ATLAS](http://www.netlib.org/atlas) is another efficient BLAS substitute,\ntailored to the architecture it compiles on. Linux users can find binary\npackages from their distribution vendors, but recompilation may be necessary\nfor optimal performance.\n\n[OpenBLAS](https://github.com/xianyi/OpenBLAS) is another alternative.\n\nTo use a non-standard library or location, set these environment variables:\n\n- `LACAML_CFLAGS` for extra compilation flags.\n- `LACAML_LIBS` to override default linking flags (`-lblas` and `-llapack`).\n\nFor CPU-specific optimization, use `-march=native`. In cloud environments,\nbe cautious as VM changes might affect the CPU. The `-ffast-math` option\ncan improve performance by allowing aggressive optimizations, but it may\nalter standard floating-point behavior, potentially affecting numerical\naccuracy and compliance with IEEE standards. Use with caution in applications\nrequiring precise numerical results. Generally, `-O3` enhances performance,\nand Lacaml should perform well with these settings, potentially utilizing\nSIMD instructions.\n\n## Contact Information and Contributing\n\nReport bugs, request features, or contribute via the\n[GitHub issue tracker](https://github.com/mmottl/lacaml/issues).\n\nFor the latest information, visit: \u003chttps://mmottl.github.io/lacaml\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmottl%2Flacaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmmottl%2Flacaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmmottl%2Flacaml/lists"}