Skip to content

gramian/matrico

main
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
doc
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

matrico 0.1 matrico

Table of Contents

Getting Started

matrico is a Scheme module for numerical matrix computations encapsulated in a CHICKEN Scheme egg.

Install and Test matrico Egg

CHICKEN_INSTALL_REPOSITORY="/my/egg/directory/" chicken-install -test matrico

Locate and Provide matrico Egg

CHICKEN_REPOSITORY_PATH="`chicken-install -repository`:/my/egg/directory/" csi

Run Demo Code

(load "RUNME.scm")

Minimal Explanation

matrico is a ...

  • ... matrix-based numerical computing environment for, and fully written in, Scheme.

  • ... self-contained implementation with minimal dependencies.

  • ... numerical linear algebra code with functional back-end design.

Background

Why matrico

  • Provide numerical capabilities to CHICKEN Scheme community.

  • Contribute scientific computing knowledge as Scheme code.

  • Educational project for author and readers.

Design Concepts

  • Provide dense two-dimensional arrays (matrix) of floating-point numbers (flonum) for CHICKEN Scheme.

  • Provide linear algebra and typical calculator functions for matrixes.

  • Use only included modules of CHICKEN Scheme.

  • A Matrix is a list of (homogeneous) vectors.

  • A Matrix uses column-major ordering of entries.

  • A Matrix uses one-based indexing.

  • A Matrix can only have real-valued flonum entries.

  • Everything is a matrix, particularly, matrixes are incompatible with Scheme's (homogeneous) vectors.

  • Matrix transformations are based on functional map-reduce approach.

Similar Projects

Function Reference

  • matrico Module
    • mx Library (User-Facing Matrix Frontend)
    • dense Module (Column Interface Specialization)
    • matrix Functor (Functional Matrix Backend)
    • f64vector Module (Homogeneous Flonum Vector Functions)
    • fpmath Module (Additional Flonum Functions)
    • utils Module (Additional Foundational Functions)
  • Extra Tools
    • check Library (Testing Helper Functions)

The matrico Module

User-Facing Function Reference (click to expand)

Module Properties

  • (matrico-ver) returns pair holding major and minor version numbers of the matrico module.

  • (matrico-help) returns void, prints help text to terminal.

  • (matrico? proc) returns boolean answering if symbol proc is an existing function starting with "mx" and prints its docstring.

Matrix Generators

  • (mx rows cols val) returns rows-by-cols matrix with all entries set to flonum val for positive fixnums rows and cols.

  • (mx% lst) returns matrix from row-major list-of-lists-offlonums lst.

  • (mx-identity dims) returns dims-by-dims identity matrix for a positive fixnum dims.

  • (mx-exchange dims) returns dims-by-dims exchange matrix for a positive fixnum dims.

  • (mx-hilbert dims) returns dims-by-dims Hilbert matrix for a positive fixnum dims.

  • (mx-pascal dims) returns dims-by-dims (lower triangular) Pascal matrix for a positive fixnum dims.

  • (mx-lehmer rows cols) returns rows-by-cols Lehmer matrix for the positive fixnums rows and cols.

  • (mx-random rows cols low upp) returns rows-by-cols uniformly distributed random matrix in the interval flonum low to flonum upp for the positive fixnums rows and cols.

  • (mx-tridiag dims low mid upp) returns dims-by-dims matrix with lower, main, upper band entries given by the flonums low, mid, upp for a positive fixnum dims.

  • (mx-linspace x y num) returns matrix of positive fixnum num row-wise linearly spaced entries with endpoints given by flonums or column-matrixes x and y.

  • (mx-logspace x y num) returns matrix of positive fixnum num row-wise (base-10) logarithmic spaced entries with endpoints given by flonums or column-matrixes x and y.

  • (mx-unit dims num) returns dims-by-one matrix of zeros except the positive fixnum num entry set to one, for a positive fixnum dims, aka canonical base vector.

  • (mx-iota dims) returns dims-by-one matrix with entries set to corresponding row index for a positive fixnum dims.

Matrix Dimensions

  • (mx-cols mat) returns fixnum of columns of matrix mat.

  • (mx-rows mat) returns fixnum of rows of matrix mat.

  • (mx-numel mat) returns fixnum of entries of matrix mat.

  • (mx-dims mat) returns fixnum of dimensions of matrix mat.

Matrix Predicates

  • (mx? any) returns boolean answering if any is a matrix.

  • (mx-col? mat) returns boolean answering if matrix mat has only a single column.

  • (mx-row? mat) returns boolean answering if matrix mat has only a single row.

  • (mx-scalar? mat) returns boolean answering if matrix mat has only a single row and single column.

  • (mx-vector? mat) returns boolean answering if matrix mat has only a single row or single column.

  • (mx-square? mat) returns boolean answering if matrix mat has the same number of rows and columns.

  • (mx-samecols? x y) returns boolean answering if matrixes x and y have same number of columns.

  • (mx-samerows? x y) returns boolean answering if matrixes x and y have same number of rows.

  • (mx-samedim? x y) returns boolean answering if matrixes x and y have same number of columns and rows.

  • (mx-any? pred mat) returns boolean answering if any entry of matrix mat fulfills predicate procedure pred.

  • (mx-all? pred mat) returns boolean answering if all entries of matrix mat fulfills predicate procedure pred.

  • (mx=? x y tol) returns boolean answering if all entry-wise distances between matrixes x and y are below tolerance flonum tol.

Matrix Accessors

  • (mx-ref11 mat) returns flonum being the top, left entry of matrix mat.

  • (mx-ref mat row col) flonum being matrix mat entry in row and column specified by positive fixnums row, col.

  • (mx-col mat col) returns matrix being matrix mat column specified by positive fixnum col.

  • (mx-row mat row) returns matrix being matrix mat row specified by positive fixnum row.

  • (mx-submatrix mat row1 row2 col1 col2) returns matrix holding entries of matrix mat in rows specified by positive fixnums row1 to row2 and columns specified by positive fixnums col1 to col2.

  • (mx-diag mat) returns column-matrix holding matrix mat diagonal entries.

  • (mx-set! mat row col val) returns void, sets entry of matrix mat in row and column specified by positive fixnums row and col to flonum or one-by-one matrix val.

Matrix Expanders

  • (mx+ x) returns matrix of entry-wise doubling of matrix x.

  • (mx+ x y) returns matrix of entry-wise addition of matrixes x and y.

  • (mx* x) returns matrix of entry-wise squaring of matrix x.

  • (mx* x y) returns matrix of entry-wise multiplication of matrixes x and y.

  • (mx- x) returns matrix of entry-wise negation of matrix x.

  • (mx- x y) returns matrix of entry-wise subtraction of matrixes x and y.

  • (mx/ x) returns matrix of entry-wise reciprocal of matrix x.

  • (mx/ x y) returns matrix of entry-wise division of matrixes x by y.

  • (mx^ x y) returns matrix of entry-wise exponentiation matrixes x to the y.

  • (mx-log b x) returns matrix of entry-wise base matrix b logarithms of matrix x.

  • (mx-dist x y) returns matrix of entry-wise absolute differences of matrixes x and y, aka distance.

  • (mx-where pred x y) returns matrix of entries of matrixes x or y based on predicate procedure pred.

  • (mx+* x a y) returns matrix of entry-wise generalized addition of matrix x with flonum a and matrix y, aka axpy.

Matrix Mappers

Entry-Wise Rounding Functions
  • (mx-round mat) returns matrix with entries of matrix mat rounded to nearest integer.

  • (mx-floor mat) returns matrix with entries of matrix mat rounded to nearest upper integer.

  • (mx-ceil mat) returns matrix with entries of matrix mat rounded to nearest lower integer.

Entry-Wise Generalized Functions
  • (mx-abs mat) returns matrix with entry-wise absolute value of matrix mat.

  • (mx-sign mat) returns matrix with entry-wise sign of matrix mat.

  • (mx-dirac mat) returns matrix with entry-wise Dirac delta of matrix mat.

Entry-Wise Trigonometric Functions
  • (mx-sin mat) returns matrix with entry-wise sine of matrix mat.

  • (mx-cos mat) returns matrix with entry-wise cosine of matrix mat.

  • (mx-tan mat) returns matrix with entry-wise tangent of matrix mat.

Entry-Wise Inverse Trigonometric Functions
  • (mx-asin mat) returns matrix with entry-wise inverse sine of matrix mat, aka arcsine.

  • (mx-acos mat) returns matrix with entry-wise inverse cosine of matrix mat, aka arccosine.

  • (mx-atan mat) returns matrix with entry-wise inverse tangent of matrix mat, aka arctangent.

Entry-Wise Hyperbolic Functions
  • (mx-sinh mat) returns matrix with entry-wise hyperbolic sine of matrix mat.

  • (mx-cosh mat) returns matrix with entry-wise hyperbolic cosine of matrix mat.

  • (mx-tanh mat) returns matrix with entry-wise hyperbolic tangent of matrix mat.

Entry-Wise Inverse Hyperbolic Functions
  • (mx-asinh mat) returns matrix with entry-wise inverse hyperbolic sine of matrix mat, aka area hyperbolic sine.

  • (mx-acosh mat) returns matrix with entry-wise inverse hyperbolic cosine of matrix mat, aka area hyperbolic cosine.

  • (mx-atanh mat) returns matrix with entry-wise inverse hyperbolic tangent of matrix mat, aka area hyperbolic tangent.

Entry-Wise Haversed Trigonometric Functions
  • (mx-hsin mat) returns matrix with entry-wise haversed sine of matrix mat.

  • (mx-hcos mat) returns matrix with entry-wise haversed cosine of matrix mat.

Entry-Wise Roots
  • (mx-sqrt mat) returns matrix with entry-wise square root of matrix mat.

  • (mx-signsqrt mat) returns matrix with entry-wise sign times square-root of absolute value of matrix mat.

Entry-Wise Logarithms
  • (mx-ln mat) returns matrix with entry-wise natural logarithm of matrix mat.

  • (mx-lb mat) returns matrix with entry-wise base-2 logarithm of matrix mat.

  • (mx-lg mat) returns matrix with entry-wise base-10 logarithm of matrix mat.

Entry-Wise Exponential
  • (mx-exp mat) returns matrix with entry-wise exponential of matrix mat.

  • (mx-gauss mat) returns matrix with entry-wise Gaussian of matrix mat.

Entry-Wise Special Functions
  • (mx-sinc mat) returns matrix with entry-wise cardinal sine of matrix mat.

  • (mx-sigm mat) returns matrix with entry-wise sigmoid of matrix mat.

  • (mx-stirling mat) returns matrix with entry-wise Stirling approximation of matrix mat.

Matrix Reducers

Sums
  • (mx-rowsum mat) returns column-matrix of summing row entries of matrix mat.

  • (mx-colsum mat) returns row-matrix of summing column entries of matrix mat.

  • (mx-sum mat) returns flonum of summing all entries of matrix mat.

Products
  • (mx-rowprod mat) returns column-matrix of multiplying row entries of matrix mat.

  • (mx-colprod mat) returns row-matrix of multiplying column entries of matrix mat.

  • (mx-prod mat) returns flonum of multiplying all entries of matrix mat.

Minima
  • (mx-rowmin mat) returns column-matrix of row-wise minima of matrix mat.

  • (mx-colmin mat) returns row-matrix of column-wise minima of matrix mat.

  • (mx-min mat) returns flonum minimum of all matrix mat entries.

Maxima
  • (mx-rowmax mat) returns column-matrix of row-wise maxima of matrix mat.

  • (mx-colmax mat) returns row-matrix of column-wise maxima of matrix mat.

  • (mx-max mat) returns flonum maximum of all matrix mat entries.

Midrange
  • (mx-rowmidr mat) returns column-matrix of row-wise midrange of matrix mat.

  • (mx-colmidr mat) returns row-matrix of column-wise midrange of matrix mat.

  • (mx-midr mat) returns flonum midrange of all matrix mat entries.

Means
  • (mx-rowmean mat typ) returns column-matrix of row-wise power means of matrix mat of type symbol typ, which can be -1, 0, 1, 2, or 'inf.

  • (mx-colmean mat typ) returns row-matrix of column-wise power means of matrix mat of type symbol typ, which can be -1, 0, 1, 2, or 'inf.

  • (mx-mean mat typ) returns flonum power mean of all matrix mat entries of type symbol typ, which can be -1, 0, 1, 2, or 'inf.

Norms
  • (mx-rownorm mat typ) returns column-matrix of row-wise matrix norms of matrix mat of type symbol typ, which can be 1, 2, or 'inf.

  • (mx-colnorm mat typ) returns row-matrix of column-wise matrix norms of matrix mat of type symbol typ, which can be 1, 2, or 'inf.

  • (mx-norm mat typ) returns flonum matrix norms of matrix mat of type symbol typ, which can be 1, 'inf, 'fro, or 'max.

Linear Algebra

  • (mx-horcat x y) returns matrix of horizontally concatenated matrixes x and y.

  • (mx-vercat x y) returns matrix of vertically concatenated matrixes x and y.

  • (mx-repeat mat rows cols) returns matrix of fixnum rows times row-wise, and fixnum cols times columns-wise repeated matrix mat.

  • (mx-vec mat) returns matrix of vertically concatenated columns of matrix mat, aka vectorization.

  • (mx-transpose mat) returns matrix of entries of matrix mat with swapped row and column indices.

  • (mx-sympart mat) returns matrix being symmetric part of square matrix mat.

  • (mx-skewpart mat) returns matrix being skey-symmetric part of square matrix mat, aka anti-symmetric part.

  • (mx-diagonal mat) returns diagonal matrix from column matrix mat.

Linear Problems
  • (mx-qr mat) returns pair of orthogonal matrix Q and upper right triangular matrix R factoring full column rank argument matrix mat, via QR.

  • (mx-solver mat) returns function returning column-matrix solving the linear (least-squares) problem of matrix mat and for argument column-matrix vec.

  • (mx-solve mat vec) returns column-matrix solving the linear (least-squares) problem of matrix mat and column-matrix vec.

  • (mx-absdet mat) returns flonum being absolute value of the determinant of matrix mat.

  • (mx-logdet mat) returns flonum being the logarithm of the determinant of matrix mat.

Traces
  • (mx-trace mat) returns flonum being sum of square matrix mat diagonal entries.

  • (mx-multrace mat) returns flonum being product of square matrix mat diagonal entries.

  • (mx-prodtrace* x yt) returns flonum being the trace of the matrix product of matrix x and transposed matrix yt.

  • (mx-prodtrace x y) returns flonum being the trace of the matrix product of matrixes x and y.

Matrix Multiplication
  • (mx-scalar x y) returns flonum resulting from scalar product of column-matrixes x and y.

  • (mx-dot* xt y) returns matrix resulting from matrix multiplication of transposed matrix xt and matrix y.

  • (mx-dot x y) returns matrix resulting from matrix multiplication of matrixes x and y.

  • (mx-gram mat) returns matrix resulting from matrix multiplication of transposed matrix mat with itself, aka Gram matrix.

  • (mx-gram* mat) returns matrix resulting from matrix multiplication of matrix mat with itself transposed.

  • (mx-square mat) returns matrix resulting from matrix multiplication of matrix mat with itself.

Multivariate Statistics
  • (mx-xcov x y) returns matrix of cross-covariances of matrixes x and y, representing columns of observations.

  • (mx-cov mat) returns matrix of covariances of matrix mat, representing columns of observations.

  • (mx-std mat) returns column matrix of standard deviations of matrix mat, representing columns of observations.

  • (mx-xcor x y) returns matrix of cross-correlations of matrixes x and y, representing columns of observations.

  • (mx-cor mat) returns matrix of correlations of matrix mat, representing columns of observations.

  • (mx-coher x y) returns flonum of distance coherence between matrixes x and y.

Analysis

  • (mx-diff mat) returns matrix of differences of consecutives columns of matrix mat.

  • (mx-trapz mat) returns column-matrix trapezoid approximate integral of matrix mat being columns data-points of rows-dimensional function.

  • (mx-ode2-hyp num fun x0 dt tf) returns states-times-steps matrix trajectory solving an ordinary differential equation, by a 2nd order hyperbolic Runge-Kutta method of fixnum num stages, with vector field procedure fun, initial state column-matrix x0, time step flonum dt, and time horizon flonum tf.

  • (mx-ode2-ssp num fun x0 dt tf) returns states-times-steps matrix trajectory solving an ordinary differential equation, by a 2nd order strong stability preserving Runge-Kutta method of fixnum num stages, with vector field procedure fun, initial state column-matrix x0, time step flonum dt, and time horizon flonum tf.

Matrix Utilities

  • (mx-print mat) returns void, prints matrix mat to terminal.

  • (mx-export str mat) returns void, writes matrix mat to new comma-separated-value (CSV) file in relative path string str.

  • (mx-save str mat) returns void, writes matrix mat to new Scheme (SCM) file in relative path string str.

  • (mx-load str) returns matrix loaded from SCM file in relative path string str.

Internal Libraries and Modules

Developer Function Reference (click to expand)

Matrix Frontend Library

Internal
  • (ensure-mx val) returns one-by-one matrix if val is flonum, or val if val is matrix.

  • (ensure-fp val) returns flonum if val is flonum, or element if val is one-by-one matrix.

  • (translate-cols idx) returns fixnum for matrix mat translated column index fixnum idx (from 1-based to 0-based and from end).

  • (translate-rows idx) returns fixnum for matrix mat translated row index fixnum idx (from 1-based to 0-based and from end).

  • (back-subst R b) column-matrix solving linear problem of upper-right triangular-matrix R and column-matrix b by back substitution.

  • (time-stepper typ fun x0 dt tf) states-times-steps matrix trajectory solving an ordinary differential equation, by method procedure typ, with vector field procedure fun, initial state column-matrix x0, time step flonum dt, and time horizon flonum tf.

Matrix Backend Library

Defines the matrix type (record) as column-major list-of-columns and provides generic basic and functional methods wrapped in a functor

  • (matrix-data mat) returns list-of-columns, generated by define-record.

  • (matrix? any) returns boolean answering if any is a matrix, generated by define-record.

  • (make-matrix lst cols) returns matrix from list lst of columns and fixnum number cols of columns, generated by define-record.

  • (make-matrix* rows cols val) returns rows-by-cols matrix with all entries set to val for fixnums rows, cols.

  • (make-matrix** lst) returns matrix from row-major list-of-lists lst.

  • (matrix-generate fun rows cols) returns rows-by-cols matrix generated procedurally from applying procedure fun (one-based), fixnums rows, cols.

  • (matrix-horcat . mat) returns matrix of horizontally concatenating matrixes from list-ofmatrixes mat.

  • (matrix-vercat . mat) returns matrix of vertically concatenating matrixes from list-of-matrixes mat.

  • (matrix-vec mat) returns column matrix of vertically concatenated columns of matrix mat, aka vectorization.

  • (matrix-cols mat) returns fixnum number of columns of matrix mat, generated by define-record.

  • (matrix-rows mat) returns fixnum number of rows of matrix mat.

  • (matrix-numel mat) returns fixnum number of entries of matrix mat.

  • (matrix-dims mat) returns fixnum number of dimensions of matrix mat.

  • (matrix-ref mat row col) returns any being matrix mat entry in fixnum row and fixnum columnS.

  • (matrix-ref00 mat) returns: flonum being the top, left entry of matrix mat.

  • (matrix-col mat col) returns matrix being matrix mat column specified by fixnum col.

  • (matrix-row mat row) returns matrix being matrix mat row specified by fixnum row.

  • (matrix-submatrix mat row1 row2 col1 col2) returns matrix holding entries of matrix mat from rows fixnums row1 to row2 in columns fixnums col1 to col2.

  • (matrix-diag mat) returns matrix holding matrix mat diagonal entries as column-matrix.

  • (matrix-set! mat row col val) returns void, sets entry of matrix mat in row fixnum row and column fixnum col to val.

  • (matrix-col? mat) returns boolean answering if matrix mat has only a single column.

  • (matrix-row? mat) returns boolean answering if matrix mat has only a single row.

  • (matrix-scalar? mat) returns boolean answering if matrix mat has only a single row and single column, aka scalar.

  • (matrix-vector? mat) returns: boolean answering if matrix mat has only a single row or single column, aka vector.

  • (matrix-square? mat) returns boolean answering if matrix mat has the same number of rows and columns.

  • (matrix-samecols? mat) returns boolean answering if matrixes x and y have same number of columns.

  • (matrix-samerows? mat) returns boolean answering if matrixes x and y have same number of rows.

  • (matrix-samedims? mat) returns boolean answering if matrixes x and y have same number of columns and rows.

  • (matrix-any? pred mat) returns boolean answering if any entry of matrix mat fulfills predicate procedure pred.

  • (matrix-all? pred mat) returns boolean answering if all entries of matrix mat fulfill predicate procedure pred.

  • (matrix-colfold fun ini mat) returns row matrix resulting from folding by two-argument procedure fun each column of **matrix** mat`.

  • (matrix-rowfold fun ini mat) returns column matrix resulting from folding by two-argument procedure fun each row of **matrix** mat`.

  • (matrix-allfold fun ini mat) returns any resulting from folding by two-argument procedure fun all **matrix** mat` entries.

  • (matrix-map fun mat) returns matrix resulting from applying procedure fun to each entry of matrix mat.

  • (matrix-broadcast fun x y) returns matrix resulting from applying procedure fun to each element of matrix x, y, expanded if necessary.

  • (matrix-transpose mat) returns matrix of entries of matrix mat with swapped row and column indices.

  • (matrix-dot* xt y) returns matrix resulting from matrix multiplication of transposed of matrix xt and matrix y.

  • (matrix-scalar x y) returns any resulting from the scalar product of column-matrixes x and y.

  • (matrix-explode mat) returns list-of-column-matrix from matrix mat.

  • (matrix-implode lst) returns matrix of horizontally concatenated list-of-column-matrixes lst.

  • (matrix-print mat) returns void, prints matrix mat to terminal.

  • (matrix-export str mat) returns void, writes matrix mat to new comma-seperated-value (CSV) file in relative path (string) str.

  • (matrix-save str mat) returns void, writes matrix mat to new Scheme (SCM) file in relative path (string) str.

  • (matrix-load str) returns matrix loaded from file in relative path (string) str.

Internal
  • (matrix-map* fun x) returns matrix resulting from applying procedure fun to each column of matrix x.

  • (matrix-map** fun x y) returns matrix resulting from applying procedure fun to each column of matrixes x and y.

Dense Column Library

Specifies generic column functions for matrix library with f64vector (flonum vector).

Homogeneous Flonum Vector Module

Provides homogeneous vector transformations analogous to vectors.

  • (f64vector-id) is string "#f64".

  • (f64vector-unfold dim fun) returns f64vector of dimension fixnum dim with procedurally generated elements by procedure fun.

  • (f64vector-concat . vec) returns f64vector of concatenated list-of-f64vectors vec.

  • (f64vector-any? pred vec) returns boolean answering if any element of f64vector vec fulfills predicate procedure pred from left to right.

  • (f64vector-all? pred vec) returns boolean answering if all elements of f64vector vec fulfill predicate procedure pred from left to right.

  • (f64vector-map fun . vec) returns f64vector resulting from applying procedure fun to all corresponding f64vectors vec elements.

  • (f64vector-map-index fun . vec) returns f64vector resulting from applying procedure fun to index and all corresponding f64vectors vec elements.

  • (f64vector-foreach fun . vec) returns void, applies procedure fun to all corresponding f64vectors vec elements.

  • (f64vector-foreach-index fun . vec) returns void, applies procedure fun to index and all corresponding f64vector vec elements.

  • (f64vector-fold fun ini . vec) returns any resulting from applying procedure fun to ini initialized accumulator and sequentially to all f64vectors vec elements from left to right.

  • (f64vector-fold* fun ini . vec) returns any resulting from applying procedure fun to ini initialized accumulator and sequentially to all f64vectors vec elements from right to left.

  • (f64vector-dot x y) returns flonum resulting from applying fused-multiply-add to zero initialized accumulator and sequentially to all f64vectors x, y elements from left to right.

Floating-Point Module

Provides additional mathematical functions, extending CHICKEN's flonum module.

  • (fp n) returns flonum from fixnum n.

  • (fp% n d) returns flonum fraction with numerator fixnum n and denominator fixnum d.

  • (fpzero?? x) returns boolean answering if flonum x is exactly zero.

  • (fpdbl x) returns flonum double of flonum x.

  • (fpsqr x) returns flonum square of flonum x.

  • (fprec x) returns flonum reciprocal of flonum x.

  • (fpdist x y) returns flonum absolute difference: |x - y| of flonums x, y.

  • (fp+* z x y) returns flonum sum with product: z + x * y of flonums x, y, z.

  • (fptau) returns flonum circle constant Tau via fraction.

  • (fpeul) returns flonum Euler number via fraction.

  • (fpphi) returns flonum golden ratio via fraction of consecutive Fibonacci numbers.

  • (fpdirac x) returns flonum Dirac delta of flonum x.

  • (fpheaviside x) returns flonum Heaviside step function of flonum x.

  • (fpsign x) returns flonum sign of flonum x.

  • (fplog2 x) returns flonum base-2 logarithm of flonum x.

  • (fplog10 x) returns flonum base-10 logarithm of flonum x.

  • (fplogb b x) returns flonum base b logarithm of flonum x.

  • (fpsinh x) returns flonum hyperbolic sine of flonum x.

  • (fpcosh x) returns flonum hyperbolic cosine of flonum x.

  • (fptanh x) returns flonum hyperbolic tangent of flonum x.

  • (fpasinh x) returns flonum area hyperbolic sine of flonum x.

  • (fpacosh x) returns flonum area hyperbolic cosine of flonum x.

  • (fpatanh x) returns flonum area hyperbolic tangent of flonum x.

  • (fphsin x) returns flonum haversed sine of flonum x.

  • (fphcos x) returns flonum haversed cosine of flonum x.

  • (fpgauss x) returns flonum Gauss bell curve function evaluation of flonum x.

  • (fpsignsqrt x) returns flonum sign times square root of absolute value of flonum x.

  • (fpsinc x) returns flonum cardinal sine function with removed singularity of flonum x.

  • (fpsigm x) returns flonum standard logistic function of flonum x, aka sigmoid.

  • (fpstirling x) returns flonum Stirling approximation of factorial of flonum x.

  • (fptaper x) returns string representation of flonum x formatted to 8 character fixed width.

Utilities Module

Provides a few base functions, macros and aliases for convenience.

  • (define-syntax-rule (name args) (body ...)) returns macro generating single-rule macro.

  • (alias aka name) returns macro replacing aka with name.

  • (must-be args) macro wrapping assert of and with variable number of arguments.

  • (comment . any) returns void.

  • nil is alias for '().

  • head is alias for car.

  • tail is alias for cdr.

  • empty? is alias for null?.

  • (fx+1 x) returns fixnum incremented fixnum x.

  • (fx-1 x) returns fixnum decremented fixnum x.

  • (fx=0? x) returns boolean answering if fixnum x is zero.

  • (fx<0? x) returns boolean answering if fixnum x is smaller than zero.

  • (fx>0? x) returns boolean answering if fixnum x is greater than zero.

  • (fx<=0? x) returns boolean answering if fixnum x is smaller or equal to zero.

  • (fx>=0? x) returns boolean answering if fixnum x is greater or equal to zero.

  • (make-list num any) returns list containing fixnum num number of elements any.

  • (sublist lst start end) returns list containing elements of list lst from indices fixnums start to end.

  • (any? pred lst) returns boolean answering if any element of list lst fulfills predicate procedure pred.

  • (all? pred lst) returns boolean answering if all elements of list lst fulfill predicate procedure pred.

  • (factorial n) returns fixnum multiplying consecutive integers up to fixnum n.

  • (binomial n k) returns fixnum binomial coefficient for fixnumss n and k based on Pascal's rule.

  • (define* (name args ...) (returns str) (body ...)) returns macro generating function binding with docstring.

  • (define* name (returns str) (body ...)) returns macro generating function binding with docstring.

  • (load* str) returns any terminal result from loaded and evaluated file with path string str.

  • (defined? sym) returns boolean answering if unquoted symbol sym is defined.

External Tools

Tools Reference (click to expand)
  • (every? lst) returns boolean answering if all elements of list lst are not false.

  • (check exe arg-ret-lst) returns boolean answering if procedure exe evaluated for car of each element of list-of-pairs arg-ret-lst corresponds to its cdr.

  • (run-tests . tst) returns 1 if any test argument tst fails, 0 otherwise.

  • (load-test str) returns any, the value of the last expression of the source file (string) str.

Performance

Please note: The author is fully aware that the performance of matrico cannot compete with current numerical environments, which predominantly utilize the highly tuned BLAS and LAPACK libraries. The following matrico benchmarks in turn are meant as an indicator to track version-by-version performance evolution of this pure Scheme implementation.

Benchmarks

LINPACK

  • Matrix dimension: 1000x1000
  • Optimization level: -O5

Run by:

make linpack

Matrix Multiplication

  • Matrix dimension: 125x125, 250x250, 500x500, 1000x1000
  • Optimization level: -O0, -O1, -O2, -O3, -O4, -O5

Run by:

make benchmark

Systems

ARM-64 Single-Board-Computer

  • CPU: Cortex-A72 (4 Cores @ 1.5Ghz)
  • RAM: 4GB (LPDDR4 @ 2400MT/s)
  • SYS: Raspberry Pi OS Lite (22-04-04)
  • SCM: CHICKEN Scheme (5.3)
LINPACK

18.9 Megaflops/s

Matrix Multiplication

benchmark plot

Development

Changelog

  • 0.1 (2022-05-01) Initial Release

Roadmap

  • [matrico] Add heat equation benchmark

  • [matrico] Add transport equation benchmark

  • [matrico] Add examples and links to documentation

  • [mx] Add rank-revealing QR and pseudo-inverse via QR

  • [mx] Add Eigenvalue decomposition and singular value decomposition

  • [mx] Add asciichart interface or functionality

  • [fpmath] Use native fp+* (CHICKEN Scheme 5.4)

  • [utils] Add map* "parallel" map

  • [check] Add more matrico tests

  • [check] Add inexact approximate equality tests

Ideas

  • Alias for .bashrc:
alias matrico='CHICKEN_REPOSITORY_PATH="`chicken-install -repository`:/my/egg/directory/" csi -R matrico'

matrico — a (🐔 λ) 🥚 for numerical schemers!