## matrico

A flonum matrix module for CHICKEN Scheme.

- matrico
- matrico Functions
- Matrix Type
- Matrix Generators
- Matrix Dimensions
- Matrix Predicates
- Matrix Accessors
- Matrix Expanders
- Matrix Mappers
- Entry-Wise Rounding Functions
- Entry-Wise Generalized Functions
- Entry-Wise Trigonometric Functions
- Entry-Wise Inverse Trigonometric Functions
- Entry-Wise Hyperbolic Functions
- Entry-Wise Inverse Hyperbolic Functions
- Entry-Wise Haversed Trigonometric Functions
- Entry-Wise Roots
- Entry-Wise Logarithms
- Entry-Wise Exponential
- Entry-Wise Special Functions

- Matrix Reducers
- Linear Algebra
- Analysis
- Matrix Utilities
- Authors
- Repository
- License
- Version History

## matrico Functions

*[procedure]*

`(matrico-ver)`

returns *pair* holding major and minor version number of the **matrico** module.

*[procedure]*

`(matrico-help)`

returns *void*, prints help text to terminal.

*[procedure]*

`(matrico? proc)`

returns *boolean* answering if *symbol* `proc` is an existing function starting with "`mx`" and prints its docstring.

## Matrix Type

*[type]*

`matrix`

a *list*-of-*f64vectors* (*flonum*-)*matrix* type. This record type is not directly accessible, and can only be manipulated through "`mx-`" functions.

## Matrix Generators

*[procedure]*

`(mx rows cols val)`

returns `rows`-by-`cols` *matrix* with all entries set to *flonum* `val` for positive *fixnum*s `rows` and `cols`.

*[procedure]*

`(mx% lst)`

returns *matrix* from row-major *list*-of-*lists*-*flonum*s `lst`.

*[procedure]*

`(mx-identity dims)`

returns `dims`-by-`dims` identity *matrix* for a positive *fixnum* `dims`.

*[procedure]*

`(mx-exchange dims)`

returns `dims`-by-`dims` exchange *matrix* for a positive *fixnum* `dims`.

*[procedure]*

`(mx-hilbert dims)`

returns `dims`-by-`dims` Hilbert *matrix* for a positive *fixnum* `dims`.

*[procedure]*

`(mx-pascal dims)`

returns `dims`-by-`dims` (lower triangular) Pascal *matrix* for a positive *fixnum* `dims`.

*[procedure]*

`(mx-lehmer rows cols)`

returns `rows`-by-`cols` Lehmer *matrix* for the positive *fixnum*s `rows` and `cols`.

*[procedure]*

`(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 *fixnum*s `rows` and `cols`.

*[procedure]*

`(mx-tridiag dims low mid upp)`

returns `dims`-by-`dims` *matrix* with lower, main, upper band entries given by the *flonum*s `low`, `mid`, `upp` for a positive *fixnum* `dims`.

*[procedure]*

`(mx-linspace x y num)`

returns *matrix* of positive *fixnum* `num` row-wise linearly spaced entries with endpoints given by *flonum*s or column-*matrix*es `x` and `y`.

*[procedure]*

`(mx-logspace x y num)`

returns *matrix* of positive *fixnum* `num` row-wise (base-10) logarithmic spaced entries with endpoints given by *flonum*s or column *matrix*es `x` and `y`.

*[procedure]*

`(mx-unit rows num)`

returns `dims`-by-one *matrix* with of zeros except the positive *fixnum* `num` entry set to one for a positive *fixnum* `dims`, aka canonical base vector.

*[procedure]*

`(mx-iota dims)`

returns `dims`-by-one *matrix* with entries set to corresponding row index for a positive *fixnum* `dims`.

## Matrix Dimensions

*[procedure]*

`(mx-cols mat)`

returns *fixnum* of columns of *matrix* `mat`.

*[procedure]*

`(mx-rows mat)`

returns *fixnum* of rows of *matrix* `mat`.

*[procedure]*

`(mx-numel mat)`

returns *fixnum* of entries of *matrix* `mat`.

*[procedure]*

`(mx-dims mat)`

returns *fixnum* of dimensions of *matrix* `mat`.

## Matrix Predicates

*[procedure]*

`(mx? any)`

returns *boolean* answering if `any` is a *matrix*.

*[procedure]*

`(mx-col? mat)`

returns *boolean* answering if *matrix* `mat` has only a single column.

*[procedure]*

`(mx-row? mat)`

returns *boolean* answering if *matrix* `mat` has only a single row.

*[procedure]*

`(mx-scalar? mat)`

returns *boolean* answering if *matrix* `mat` has only a single row and single column.

*[procedure]*

`(mx-vector? mat)`

returns *boolean* answering if *matrix* `mat` has only a single row or single column.

*[procedure]*

`(mx-square? mat)`

returns *boolean* answering if *matrix* `mat` has the same number of rows and columns.

*[procedure]*

`(mx-samecols? x y)`

returns *boolean* answering if *matrix*es `x` and `y` have same number of columns.

*[procedure]*

`(mx-samerows? x y)`

returns *boolean* answering if *matrix*es `x` and `y` have same number of rows.

*[procedure]*

`(mx-samedim? x y)`

returns *boolean* answering if *matrix*es `x` and `y` have same number of columns and rows.

*[procedure]*

`(mx-any? pred mat)`

returns *boolean* answering if any entry of *matrix* `mat` fulfills predicate *procedure* `pred`.

*[procedure]*

`(mx-all? pred mat)`

returns *boolean* answering if all entries of *matrix* `mat` fulfills predicate *procedure* `pred`.

*[procedure]*

`(mx=? x y tol)`

returns *boolean* answering if all entry-wise distances between *matrix*es `x` and `y` are below tolerance *flonum* `tol`.

## Matrix Accessors

*[procedure]*

`(mx-ref11 mat)`

returns *flonum* being the top, left entry of *matrix* `mat`.

*[procedure]*

`(mx-ref mat row col)`

returns *flonum* being *matrix* `mat` entry in row and column specified by positive *fixnum*s `row`, `col`.

*[procedure]*

`(mx-col mat col)`

returns *matrix* being *matrix* `mat` column specified by positive *fixnum* `col`.

*[procedure]*

`(mx-row mat row)`

returns *matrix* being *matrix* `mat` row specified by positive *fixnum* `row`.

*[procedure]*

`(mx-submatrix mat row1 row2 col1 col2)`

returns *matrix* holding entries of *matrix* `mat` in rows specified by positive *fixnum*s `row1` to `row2` and columns specified by positive *fixnum*s `col1` to `col2`.

*[procedure]*

`(mx-diag mat)`

returns column-*matrix* holding square *matrix* `mat` diagonal entries.

*[procedure]*

`(mx-set! mat row col val)`

returns *void*, sets entry of *matrix* `mat` in row and column specified by positive *fixnum*s `row` and `col` to *flonum* or one-by-one *matrix* `val`.

## Matrix Expanders

*[procedure]*

`(mx+ x)`

returns *matrix* of entry-wise doubling of *matrix* `x`.

*[procedure]*

`(mx+ x y)`

returns *matrix* of entry-wise addition of *matrix*es `x` and `y`.

*[procedure]*

`(mx* x)`

returns *matrix* of entry-wise squaring of *matrix* `x`.

*[procedure]*

`(mx* x y)`

returns *matrix* of entry-wise multiplication of *matrix*es `x` and `y`.

*[procedure]*

`(mx- x)`

returns *matrix* of entry-wise negation of *matrix* `x`.

*[procedure]*

`(mx- x y)`

returns *matrix* of entry-wise subtraction of *matrix*es `x` and `y`.

*[procedure]*

`(mx/ x)`

returns *matrix* of entry-wise reciprocal of *matrix* `x`.

*[procedure]*

`(mx/ x y)`

returns *matrix* of entry-wise division of *matrix*es `x` by `y`.

*[procedure]*

`(mx^ x y)`

returns *matrix* of entry-wise exponentiation *matrix*es `x` to the `y`.

*[procedure]*

`(mx-log b x)`

returns *matrix* of entry-wise base *matrix* `b` logarithms of *matrix* `x`.

*[procedure]*

`(mx-dist x y)`

returns *matrix* of entry-wise absolute differences of *matrix*es `x` and `y`, aka distance.

*[procedure]*

`(mx-where pred x y)`

returns *matrix* of entries of *matrix*es `x` or `y` based on predicate *procedure* `pred`.

*[procedure]*

`(mx+* a x y)`

returns *matrix* of entry-wise generalized addition of *matrix* `x` with *flonum* `a` and *matrix* `y`.

## Matrix Mappers

### Entry-Wise Rounding Functions

*[procedure]*

`(mx-round mat)`

returns *matrix* with entries of *matrix* `mat` rounded to nearest integer.

*[procedure]*

`(mx-floor mat)`

returns *matrix* with entries of *matrix* `mat` rounded to nearest upper integer.

*[procedure]*

`(mx-ceil mat)`

returns *matrix* with entries of *matrix* `mat` rounded to nearest lower integer.

### Entry-Wise Generalized Functions

*[procedure]*

`(mx-abs mat)`

returns *matrix* with entry-wise absolute value of *matrix* `mat`.

*[procedure]*

`(mx-sign mat)`

returns *matrix* with entry-wise sign of *matrix* `mat`.

*[procedure]*

`(mx-dirac mat)`

returns *matrix* with entry-wise Dirac delta of *matrix* `mat`.

### Entry-Wise Trigonometric Functions

*[procedure]*

`(mx-sin mat)`

returns *matrix* with entry-wise sine of *matrix* `mat`.

*[procedure]*

`(mx-cos mat)`

returns *matrix* with entry-wise cosine of *matrix* `mat`.

*[procedure]*

`(mx-tan mat)`

returns *matrix* with entry-wise tangent of *matrix* `mat`.

### Entry-Wise Inverse Trigonometric Functions

*[procedure]*

`(mx-asin mat)`

returns *matrix* with entry-wise inverse sine of *matrix* `mat`, aka arcsine.

*[procedure]*

`(mx-acos mat)`

returns *matrix* with entry-wise inverse cosine of *matrix* `mat`, aka arccosine.

*[procedure]*

`(mx-atan mat)`

returns *matrix* with entry-wise inverse tangent of *matrix* `mat`, aka arctangent.

### Entry-Wise Hyperbolic Functions

*[procedure]*

`(mx-sinh mat)`

returns *matrix* with entry-wise hyperbolic sine of *matrix* `mat`.

*[procedure]*

`(mx-cosh mat)`

returns *matrix* with entry-wise hyperbolic cosine of *matrix* `mat`.

*[procedure]*

`(mx-tanh mat)`

returns *matrix* with entry-wise hyperbolic tangent of *matrix* `mat`.

### Entry-Wise Inverse Hyperbolic Functions

*[procedure]*

`(mx-asinh mat)`

returns *matrix* with entry-wise inverse hyperbolic sine of *matrix* `mat`, aka area hyperbolic sine.

*[procedure]*

`(mx-acosh mat)`

returns *matrix* with entry-wise inverse hyperbolic cosine of *matrix* `mat`, aka area hyperbolic cosine.

*[procedure]*

`(mx-atanh mat)`

returns *matrix* with entry-wise inverse hyperbolic tangent of *matrix* `mat`, aka area hyperbolic tangent.

### Entry-Wise Haversed Trigonometric Functions

*[procedure]*

`(mx-hsin mat)`

returns *matrix* with entry-wise haversed sine of *matrix* `mat`.

*[procedure]*

`(mx-hcos mat)`

returns *matrix* with entry-wise haversed cosine of *matrix* `mat`.

### Entry-Wise Roots

*[procedure]*

`(mx-sqrt mat)`

returns *matrix* with entry-wise square root of *matrix* `mat`.

*[procedure]*

`(mx-signsqrt mat)`

returns *matrix* with entry-wise sign times square-root of absolute value of *matrix* `mat`.

### Entry-Wise Logarithms

*[procedure]*

`(mx-ln mat)`

returns *matrix* with entry-wise natural logarithm of *matrix* `mat`.

*[procedure]*

`(mx-lb mat)`

returns *matrix* with entry-wise base-2 logarithm of *matrix* `mat`.

*[procedure]*

`(mx-lg mat)`

returns *matrix* with entry-wise base-10 logarithm of *matrix* `mat`.

### Entry-Wise Exponential

*[procedure]*

`(mx-exp mat)`

returns *matrix* with entry-wise exponential of *matrix* `mat`.

*[procedure]*

`(mx-gauss mat)`

returns *matrix* with entry-wise Gaussian of *matrix* `mat`.

### Entry-Wise Special Functions

*[procedure]*

`(mx-sinc mat)`

returns *matrix* with entry-wise cardinal sine of *matrix* `mat`.

*[procedure]*

`(mx-sigm mat)`

returns *matrix* with entry-wise sigmoid of *matrix* `mat`.

*[procedure]*

`(mx-stirling mat)`

returns *matrix* with entry-wise Stirling approximation of *matrix* `mat`.

## Matrix Reducers

### Sums

*[procedure]*

`(mx-rowsum mat)`

returns column-*matrix* of summing row entries of *matrix* `mat`.

*[procedure]*

`(mx-colsum mat)`

returns row-*matrix* of summing column entries of *matrix* `mat`.

*[procedure]*

`(mx-sum mat)`

returns *flonum* of summing all entries of *matrix* `mat`.

### Products

*[procedure]*

`(mx-rowprod mat)`

returns column-*matrix* of multiplying row entries of *matrix* `mat`.

*[procedure]*

`(mx-colprod mat)`

returns row-*matrix* of multiplying column entries of *matrix* `mat`.

*[procedure]*

`(mx-prod mat)`

returns *flonum* of multiplying all entries of *matrix* `mat`.

### Minima

*[procedure]*

`(mx-rowmin mat)`

returns column-*matrix* of row-wise minima of *matrix* `mat`.

*[procedure]*

`(mx-colmin mat)`

returns row-*matrix* of column-wise minima of *matrix* `mat`.

*[procedure]*

`(mx-min mat)`

returns *flonum* minimum of all *matrix* `mat` entries.

### Maxima

*[procedure]*

`(mx-rowmax mat)`

returns column-*matrix* of row-wise maxima of *matrix* `mat`.

*[procedure]*

`(mx-colmax mat)`

returns row-*matrix* of column-wise maxima of *matrix* `mat`.

*[procedure]*

`(mx-max mat)`

returns *flonum* maximum of all *matrix* `mat` entries.

### Midrange

*[procedure]*

`(mx-rowmidrange mat)`

returns column-*matrix* of row-wise midrange of *matrix* `mat`.

*[procedure]*

`(mx-colmidrange mat)`

returns row-*matrix* of column-wise midrange of *matrix* `mat`.

*[procedure]*

`(mx-midrange mat)`

returns *flonum* midrange of all *matrix* `mat` entries.

### Means

*[procedure]*

`(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`.

*[procedure]*

`(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`.

*[procedure]*

`(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

*[procedure]*

`(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`.

*[procedure]*

`(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`.

*[procedure]*

`(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

*[procedure]*

`(mx-horcat x y)`

returns *matrix* of horizontally concatenated *matrix*es `x` and `y`.

*[procedure]*

`(mx-vercat x y)`

returns *matrix* of vertically concatenated *matrix*es `x` and `y`.

*[procedure]*

`(mx-repeat mat rows cols)`

returns *matrix* of *fixnum* `rows` times row-wise, and *fixnum* `cols` times columns-wise repeated *matrix* `mat`.

*[procedure]*

`(mx-vec mat)`

returns *matrix* of vertically concatenated columns of *matrix* `mat`, aka vectorization.

*[procedure]*

`(mx-transpose mat)`

returns *matrix* of entries of *matrix* `mat` with swapped row and column indices.

*[procedure]*

`(mx-sympart mat)`

returns *matrix* being symmetric part of square *matrix* `mat`.

*[procedure]*

`(mx-skewpart mat)`

returns *matrix* being skey-symmetric part of square *matrix* `mat`, aka anti-symmetric part.

*[procedure]*

`(mx-diagonal mat)`

returns diagonal *matrix* from column *matrix* `mat`.

### Linear Problems

*[procedure]*

`(mx-qr mat)`

returns *pair* of orthogonal *matrix* (Q) and upper right triangular *matrix* (R) factoring full column rank argument *matrix* `mat`.

*[procedure]*

`(mx-solver mat)`

function returning column-*matrix* solving the linear (least-squares) problem of *matrix* `mat` and for argument column-*matrix* `vec`.

*[procedure]*

`(mx-solve mat vec)`

returns column-*matrix* solving the linear problem of *matrix* `mat` and column-*matrix* `vec`.

*[procedure]*

`(mx-absdet mat)`

returns *flonum* being absolute value of the determinant of *matrix* `mat`.

*[procedure]*

`(mx-logdet mat)`

returns *flonum* being the logarithm of the determinant of *matrix* `mat`.

### Traces

*[procedure]*

`(mx-trace mat)`

returns *flonum* being sum of square *matrix* `mat` diagonal entries.

*[procedure]*

`(mx-multrace mat)`

returns *flonum* being product of square *matrix* `mat` diagonal entries.

*[procedure]*

`(mx-prodtrace* x yt)`

returns *flonum* being the trace of the matrix product of *matrix* `x` and transposed *matrix* `yt`.

*[procedure]*

`(mx-prodtrace x y)`

returns *flonum* being the trace of the matrix product of *matrix*es `x` and `y`.

### Matrix Multiplication

*[procedure]*

`(mx-scalar x y)`

returns *flonum* resulting from scalar product of column-*matrix*es `x` and `y`.

*[procedure]*

`(mx-dot* xt y)`

returns *matrix* resulting from matrix multiplication of transposed *matrix* `xt` and *matrix* `y`.

*[procedure]*

`(mx-dot x y)`

returns *matrix* resulting from matrix multiplication of *matrix*es `x` and `y`.

*[procedure]*

`(mx-gram mat)`

returns *matrix* resulting from matrix multiplication of transposed *matrix* `mat` with itself, aka Gram matrix.

*[procedure]*

`(mx-gram* mat)`

returns *matrix* resulting from matrix multiplication of *matrix* `mat` with itself transposed.

*[procedure]*

`(mx-square mat)`

returns *matrix* resulting from matrix multiplication of *matrix* `mat` with itself.

### Multivariate Statistics

*[procedure]*

`(mx-xcov x y)`

returns *matrix* of cross-covariances of *matrix*es `x` and `y`, representing columns of observations.

*[procedure]*

`(mx-cov mat)`

returns *matrix* of covariances of *matrix* `mat`, representing columns of observations.

*[procedure]*

`(mx-std mat)`

returns column *matrix* of standard deviations of *matrix* `mat`, representing columns of observations.

*[procedure]*

`(mx-xcor x y)`

returns *matrix* of cross-correlations of *matrix*es `x` and `y`, representing columns of observations.

*[procedure]*

`(mx-cor mat)`

returns *matrix* of correlations of *matrix* `mat`, representing columns of observations.

*[procedure]*

`(mx-coher x y)`

returns *flonum* of distance coherence between *matrix*es `x` and `y`.

## Analysis

*[procedure]*

`(mx-diff mat)`

returns *matrix* of differences of consecutives columns of *matrix* `mat`.

*[procedure]*

`(mx-trapz mat)`

returns column-*matrix* trapezoid approximate integral of *matrix* `mat` being columns data-points of rows-dimensional function.

*[procedure]*

`(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`.

*[procedure]*

`(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

*[procedure]*

`(mx-print mat)`

returns *void*, prints *matrix* `mat` to terminal.

*[procedure]*

`(mx-export str mat)`

returns *void*, writes *matrix* `mat` to new comma-separated-value (CSV) file with name *string* `str`.

*[procedure]*

`(mx-save str mat)`

returns *void*, writes *matrix* `mat` to new Scheme (SCM) file with name *string* `str`.

*[procedure]*

`(mx-load str)`

returns *matrix* loaded from SCM file in relative path specified by *string* `str`.

## Authors

## Repository

## License

Copyright (c) 2022 Christian Himpe. zlib-acknowledgement license

## Version History

- 0.1
- Initial Release