Interfaces/Matrix Market

Introduction

Matrix Market Exchange Formats are a set of human readable, ASCII-based file formats designed to facilitate the exchange of numeric arrays of rank 2, possibly structured.

Data in this formats may be processed by utility mm from math/mt addon.

Let's prepare some arrays to play with:

   NB. load mt addon to get mm utility
   load 'math/mt'

   NB. Coordinate (sparse) Pattern (boolean) Symmetric 4×4-matrix
   $.^:_1 Acps=. 1 ((<"1) 6 2 $ 0 0 0 1 1 0 1 3 2 2 3 1)} 1 $. 4 4 ; 0 1 ; 0
1 1 0 0
1 0 0 1
0 0 1 0
0 1 0 0
   
   NB. Array (dense) Integer General 2×3-matrix
   ] Aaig=. _10 + ? 2 3 $ 20
 0 5 8
_6 3 2
   
   NB. Array (dense) Complex skeW-Hermitian 3×3-matrix
   ] Aacw=. (</~@i.@#)`(,: +@:-@|:)}@trl0_mt_ j./ _1 2 p. ? 2 3 3 $ 0
                  0  0.440151j0.917352  0.632934j_0.385469
 _0.440151j0.917352                  0 _0.084053j_0.575425
_0.632934j_0.385469 0.084053j_0.575425                   0

Export from J array

Use the monad mm_mtmm_ . Input is a J array. Output is a string in appropriate Matrix Market exchange format.

   ] MMcps=. mm_mtmm_ Acps
%%matrixmarket matrix coordinate pattern symmetric
4 4 4
1 1
2 1
3 3
4 2

   ] MMaig=. mm_mtmm_ Aaig
%%matrixmarket matrix array integer general
2 3
 0
-6
 5
 3
 8
 2

   ] MMacw=. mm_mtmm_ Aacw
%%matrixmarket matrix array complex skew-hermitian
3 3
                   0                    0
  -0.440151072537738  0.91735201464973648
-0.63293415924289653  -0.3854688889235558
                   0                    0
0.084053008844930721 -0.57542528939613313
                   0                    0

Import into J array

Use the monad mm_mtmm_^:_1 . Input is a string in one of Matrix Market exchange formats. Output is a J array.

   NB. import back, then validate for each test array
   
   Acps2=. mm_mtmm_^:_1 MMcps
   Acps -: Acps2
1
   
   Aaig2=. mm_mtmm_^:_1 MMaig
   Aaig -: Aaig2
1
   
   Aacw2=. mm_mtmm_^:_1 MMacw
   Aacw -: Aacw2
1

Verify

To verify mm utility for direct and inverse invocations by data set pre-defined, use a verification script from mt addon:

   (0!:3) < jpath '~addons/math/mt/verify/5_mm.ijs'  NB. silent: will return result as boolean
1
   (0!:2) < jpath '~addons/math/mt/verify/5_mm.ijs'  NB. or verbose: will also display sentences probed
... (output is skipped)
1

Benchmark

A sparse complex symmetric 2534×2534-matrix with 463360 non-sparse elements Bai/qc2534 was selected. Its file qc2534.mtx of size 12 Mbytes was placed into ~temp directory. It has the header:

%%MatrixMarket matrix coordinate complex symmetric
%-------------------------------------------------------------------------------
% UF Sparse Matrix Collection, Tim Davis
% http://www.cise.ufl.edu/research/sparse/matrices/Bai/qc2534
% name: Bai/qc2534
% [MODEL H2+ IN AN ELECTROMAGNETIC FIELD, S.I. CHU]
% id: 326
% date: 1991
% author: S. Chu
% ed: Z. Bai, D. Day, J. Demmel, J. Dongarra
% fields: title A name id date author ed kind
% kind: electromagnetics problem
%-------------------------------------------------------------------------------
2534 2534 232947

Let's go:

   NB. load the file into a string noun and check its size
   $ str=. fread2_mtmm_ '~temp/qc2534.mtx'
12028372
   NB. measure an importing
   timespacex 'arr=. mm_mtmm_^:_1 str'
1.0429 2.06581e8
   NB. check the array size
   $ arr
2534 2534
   NB. measure an exporting
   timespacex 'str=. mm_mtmm_ arr'
0.662591 1.09058e8

Implementation features

	standard	mm implementation
Is non-zero sparse element allowed?	no	no
Are arrays of rank > 2 allowed?	no	yes
Is skew-Hermitian symmetry supported?	no	yes
Is 'array pattern' qualifiers combination allowed?	no	yes
Are extended, rational, quaternion, and octonion datatypes supported?	no	no
Are inf, +inf, and -inf constants supported?	yes	in import only
Are nan, +nan, and -nan constants supported?	yes	in import only