Addons/math/mt

From J Wiki
Jump to navigation Jump to search
User Guide | Installation | Development | Categories | Git | Build Log

math/mt - Matrix Toolbox.

mt is a set of routines for solving some problems in matrix algebra: transforming, decomposing, reducing to condensed form, factorization, equation solving, function applying, condition number estimating. It's based mostly on LAPACK algorithms.

Browse history, source and examples using GitHub.

Installation

If you prefer jconsole or Qt Jconsole: 

   load 'pacman'
   'update' jpkg ''
Updating server catalog...
Local JAL information has never been updated.
Installed addons are up to date, 1 addon are not yet installed.
The base library is up to date.
   'install' jpkg 'math/mt'
Installing 1 package
Downloading math/mt...
Installing math/mt...
Done.
All available packages are installed and up to date.
The base library is up to date.

Or use Package Manager.

Load math/mt addon with the following line: 

   load 'math/mt'

Addon self-testing

Testing is performed with random input data generated after the process is started.

Testing routines output the table of following columns:

  • 'sentence' - command used to test, either verb or bonded verb
  • 'rcond' - reciprocal of condition number of a square matrix, or NaN
  • 'rel fwd err' - relative forward error if possible, or NaN
  • 'rel bwd err' - relative backward error if possible, or NaN
  • 'time, sec.' - execution time, in seconds
  • 'space' - space required to execute command, in bytes

While testing, output is directed into:

  • console (always)
  • global noun TESTLOG (always)
  • log file (optional, depends on global noun TESTLOGFILE value)

To compare mt routines against alternatives, the following addons would be installed:

  • math/lapack of latest version
  • math/misc

First of all, let's define appropriate random array generator: 

   NB. Monad to generate an array of shape y
   NB. with elements distributed as U(0,1)
   rag=. ?@$&0

For various generator examples see rand.ijs .

Self-test the entire add-on 

   NB. use rag to test addon by random matrices of size 150x150,
   NB. see mt.ijs
   rag test_mt_ 150 150

Be ready for long execution time for matrices of big size (>500).

Self-test the group of algorithms 

   NB. use rag to test low-level algorithms by random matrices of size 150x150,
   NB. see mt.ijs
   rag testlow_mt_ 150 150

   NB. use rag to test mid-level algorithms by random matrices of size 150x150,
   NB. see mt.ijs
   rag testmid_mt_ 150 150

   NB. use rag to test high-level algorithms by random matrices of size 150x150,
   NB. see mt.ijs
   rag testhigh_mt_ 150 150

Self-test particular file 

   NB. use rag to test xxtrfxxxxx verbs (triangular factorization)
   NB. by random matrices of size 150x150, see trf.ijs
   rag testtrf_mt_ 150 150

Self-test particular set of verbs by pre-defined matrix 

   NB. generate random general matrix of size 150x150
   A=. rag 150 150

   NB. use A to test getrfxxxx (triangular factorization of
   NB. a general matrix) by pre-defined matrix, see trf.ijs
   testgetrf_mt_ A

Addon verifying

Verifying is performed with pre-defined hard-coded input and output data which were selected thoroughly.

Verifying routine outputs to console a text, where each line contains:

  • name of module verified
  • tests probed counter
  • tests failed counter

Verifying routine returns integer 2-vector of tests counters (probed,verified). 

   verify_mt_ ''
module: mm, tests probed: 152, failed: 0
152 0

Currently only the mm module provides a verification capability.

Addon benchmarking

See Benchmarking page.

Example usage

Let's make some arrays to play with: 

   A=. rag 5 5
   X=. rag 5 3
   B=. A mp_mt_ X

Now perform some calculations: 

   NB. do triangular factorization: P*L1*U=A, see trf.ijs
   'ip L1U'=. getrfpl1u_mt_ A
   L1=. trl1_mt_ L1U
   U=. tru_mt_ L1U
   P=. ip2P_mt_ ip
   A -: P mp_mt_ L1 mp_mt_ U
1

   NB. solve equation: A*X=B, see sv.ijs
   Xapprox=. A gesvax_mt_ B
   X -: Xapprox
1

   NB. do QR factorization: Q*R=A, see qf.ijs
   QfR=. geqrf_mt_ A
   Q=. ungqr_mt_ QfR
   R=. tru_mt_ QfR
   A -: Q mp_mt_ R
1

   NB. raise A to integer powers: A^i.30, see pow.ijs
   Apows=. (i. 30) gepow_mt_ A                            NB. via repeated squaring, O(n^3 * log(30)) FLOPs
   ApowsSF=. (idmat_mt_ # A) 0} |.!.0 mp_mt_/\ 30 # ,: A  NB. straightforward, O(n^3 * 30) FLOPs
   Apows -: ApowsSF
1

   NB. find matrix exponential: E:=exp(A), see exp.ijs
   E=. geexp_mt_ A                                        NB. by scaling and squaring method
   Eapprox=. +/ Apows % ! i. 30                           NB. by finite summation
   E -: Eapprox
1

mt for users

mt follows LAPACK's name conventions whenever possible, e.g. getrf verb of mt corresponds to both DGETRF and ZGETRF (xGETRF) subroutines of LAPACK. Floating point datatype input usually forces J-actor (verb/adverb/conjunction) to behave like a Dxxxxx counterpart in LAPACK. Complex datatype input usually forces J-actor to behave like a Zxxxxx counterpart.

Most J-actors in mt has particular specialization. E.g. larftbc corresponds to LAPACK subroutine xLARFT('B','C',...), larftfr corresponds to xLARFT('F','R',...), and so on.

When referenced, names may be grouped by wildcard 'x', e.g.:

  • xxexp means: geexp, diexp, heexp
  • getrfxxxx means: getrflu1p, getrfpl1u, getrfpu1l, getrful1p

Similarity of J-actor in mt to its correspondent counterpart in LAPACK has some levels:

  • implementation: input and output storage layouts are the same, algorighm is essentially the same; e.g. gesvax implements xGESV
  • model: input or output storage layouts may differ, or algorighm is differrent; e.g. getrf models xGETRF
  • simulation: input or output storage layouts are differrent, algorighm is essentially differrent; e.g. gecon1 simulates xGECON('1')
  • similar: provides similar functionality, but is completely different; e.g. hetrfpl is similar to xHETRF('L')
  • new: provides new functionality; e.g. geexp

Currently only the limited set of routines is implemented, see the MATRIX.

mt for developers

lapack2 J addon uses original LAPACK library as backend. So, it is rather simple to add new interface for any LAPACK subroutine. But, there is excessive data pre- and post-processing, and addon user is limited to data types and storage layouts provided by Fortran.

As opposed to lapack2 J addon, mt is written on pure J and doesn't require LAPACK for underlying calculations. So, any J data types and storage layouts can be used. But, adding new stuff requires programming of algorithms from scratch.

The file template.ijs may be used as a seed to start with.

Debug

Any verb can be switched into the debugging mode by applying a conjunction dbg (file dbg.ijs). Under this mode, verb outputs in console some additional information. Verbosity of debug is defined by global noun DEBUG (file mt.ijs). E.g.: 

   NB. statement to debug
   +/\ 100 20 3
100 120 123

   NB. default verbosity level is 2, meaning output of rank and
   NB. valency, locale name, input and output shapes and values

   NB. debug (+/) with current verbosity level (2)
   (+/ dbg_mt_ '+/')\ 100 20 3
┌──┬─────┬─────┬────┬─┬─┬───┐
│+/│MONAD│_ _ _│base│y│1│100│
└──┴─────┴─────┴────┴─┴─┴───┘
┌──┬───────┬────┬──────┬┬───┐
│+/│SUCCEED│base│result││100│
└──┴───────┴────┴──────┴┴───┘
┌──┬─────┬─────┬────┬─┬─┬──────┐
│+/│MONAD│_ _ _│base│y│2│100 20│
└──┴─────┴─────┴────┴─┴─┴──────┘
┌──┬───────┬────┬──────┬┬───┐
│+/│SUCCEED│base│result││120│
└──┴───────┴────┴──────┴┴───┘
┌──┬─────┬─────┬────┬─┬─┬────────┐
│+/│MONAD│_ _ _│base│y│3│100 20 3│
└──┴─────┴─────┴────┴─┴─┴────────┘
┌──┬───────┬────┬──────┬┬───┐
│+/│SUCCEED│base│result││123│
└──┴───────┴────┴──────┴┴───┘
100 120 123

   NB. set verbosity level to 1, meaning output of rank and
   NB. valency, locale name, input's and output's shapes without values
   DEBUG_mt_=: 1

   NB. debug (+/) with current verbosity level (1)
   (+/ dbg_mt_ '+/')\ 100 20 3
┌──┬─────┬─────┬────┬─┬─┐
│+/│MONAD│_ _ _│base│y│1│
└──┴─────┴─────┴────┴─┴─┘
┌──┬───────┬────┬──────┬┐
│+/│SUCCEED│base│result││
└──┴───────┴────┴──────┴┘
┌──┬─────┬─────┬────┬─┬─┐
│+/│MONAD│_ _ _│base│y│2│
└──┴─────┴─────┴────┴─┴─┘
┌──┬───────┬────┬──────┬┐
│+/│SUCCEED│base│result││
└──┴───────┴────┴──────┴┘
┌──┬─────┬─────┬────┬─┬─┐
│+/│MONAD│_ _ _│base│y│3│
└──┴─────┴─────┴────┴─┴─┘
┌──┬───────┬────┬──────┬┐
│+/│SUCCEED│base│result││
└──┴───────┴────┴──────┴┘
100 120 123

   NB. set verbosity level to 0, meaning
   NB. execute original verb unmangled
   DEBUG_mt_=: 0

   NB. debug (+/) with current verbosity level (0)
   (+/ dbg_mt_ '+/')\ 100 20 3
100 120 123

Authors

Authorship of mt addon code belongs to various authors. All the authors are listed below:

Name File Orignial name Author Published Link
icut struct.ijs bcut1 Roger Hui 2005-11-24 02:11 [JWiki] Essays/Block Matrix Inverse
issym mm.ijs sym Roger Hui 2003-08-08 00:46:00 [Jgeneral] Testing whether array is symmetric

see also [JWiki] Essays/Symmetric Array

upd struct.ijs Amend Oleg Kobchenko 2007-03-02 14:15:54 [Jprogramming] Transform to Amend

All the rest code was written by Igor Zhuravlov.

See Also

Retrieved from "https://code.jsoftware.com/mediawiki/index.php?title=Addons/math/mt&oldid=47119"