The Matrix Market Exchange Formats Initial Design

NISTIR5935TheMatrixMarketExchangeFormats:InitialDesignRonaldF.BoisvertRoldanPozoKarinA.RemingtonU.S.DepartmentofCommerceTechnologyAdministrationNationalInstituteofStandardsandTechnologyComputingandAppliedMathematicsLaboratoryGaithersburg,MD20899USADecember1996TheMatrixMarketExchangeFormats:InitialDesignRonaldF.Boisvert,RoldanPozoandKarinA.RemingtonAppliedandComputationalMathematicsDivisionNationalInstituteofStandardsandTechnologyGaithersburg,MD20899USA.AbstractWeproposeelementaryASCIIexchangeformatsformatrices.Specicinstancesoftheformataredenedfordenseandsparsematriceswithreal,complex,integerandpatternentries,withspecialcasesforsymmetric,skew-symmetricandHer-mitianmatrices.Sparsematricesarerepresentedinacoordinatestorageformat.Theoveralllestructureisdesignedtoallowfuturedenitionofotherspecializedmatrixformats,aswellasforobjectsotherthanmatrices.Contents1Introduction11.1CoordinateFormatforSparseMatrices:::::::::::::::::::::::::::::21.2ArrayFormatforDenseMatrices::::::::::::::::::::::::::::::::52SpecicationoftheBaseMMFileFormat63SpecicationofMMFormatsforMatrices73.1CoordinateFormatsforSparseMatrices::::::::::::::::::::::::::::73.2ArrayFormatsforDenseMatrices:::::::::::::::::::::::::::::::84ExtendingtheBaseMMFormats94.1StructuredComments::::::::::::::::::::::::::::::::::::::94.2FormatSpecializations.:::::::::::::::::::::::::::::::::::::124.3ExtendingtheMMTypeCode:::::::::::::::::::::::::::::::::13Email:[e-mail],[e-mail],[e-mail],R.PozoandK.A.Remington1IntroductionTheMatrixMarket(MM)exchangeformatsprovideasimplemechanismtofacilitatetheexchangeofmatrixdata.Inparticular,theobjectivehasbeentodeneaminimalbaseASCIIleformatwhichcanbeveryeasilyexplainedandparsed,butcanbeeasilyadaptedtoapplicationswithamorerigidstructure,orextendedtorelateddataobjects.ThisleformatistheprimaryformatusedbytheMatrixMarket[1],avisualdatabaseofmatrixtestdataavailableontheWorldWideWeb1.TheMMexchangeformatformatricesisreallyacollectionofaliatedformatswhichsharedesignelements.Inourinitialspecication,twomatrixformatsaredened.1.CoordinateFormatAleformatsuitableforrepresentinggeneralsparsematrices.Onlynonzeroentriesareprovided,andthecoordinatesofeachnonzeroentryisgivenexplicitly.ThiswillbeillustratedinExamples1and2.2.ArrayFormatAleformatsuitableforrepresentinggeneraldensematrices.Allentriesarepro-videdinapre-dened(column-oriented)order.ThiswillbeillustratedinExample3.Severalinstancesofeachofthesebasicformatsaredened.Theseareobtainedbyspecifyinganarithmeticeldforthematrixentries(i.e.,real,complex,integer,pattern)andasymmetrystructurewhichmayreducethesizeofthedatale(i.e.general,symmetric,skew-symmetric,Hermitian).TheMMdesignovercomessomeofthedicultieswithexistingschemes.ThemostwellknownistheHarwell-Boeing(HB)SparseMatrixFormat[2].Manymatriceshavebeenencodedusingthisformat,mostnotablythosecomprisingtheHarwell-BoeingSparseMatrixCollection(ReleaseI).Unfortunately,theHBspecicationissomewhatcomplex,diculttoparsefromlanguagesotherthanFortran,biasedinfavorofcompressedcolumnrepresentation,andnoteasilyextensible.SomeofthesefactorsmayhaveimpededthemorewidespreaduseoftheHBformat.Recently,agroupatNASAAmesproposedanalternateformat(GAMFF)[3].Thiswasmotivatedmainlyduetotheneedtoproducealeformattorepresentgraphs.Aspeci-cationwhichincludedgraphs,sparsematrices,anddensematriceswasdeveloped,andalargevarietyofsuchmatrixandgraphleswereconvertedtothisformat2.AlthoughtheGAMFFformatissomewhatsimplerandmoreextensiblethanHB,itssparsematrixsubsetremainscloselytiedtotheHBcompressedcolumnformat.1://:InitialDesign3Intheremainderofthissection,wedescribethecoordinateandarraymatrixformatsinformally,providingseveralexamples,whileinSection2,wedetailtheformalspecica-tionoftheMMfamilyofformats.InSection3,weelaborateonthecoordinateandarraymatrixformats.Finally,inSection4weoutlinesomeoftheguidingprinciplesthatweusedindesigningtheseformats,focusingespeciallyonthefeaturesusedtoassureeasyextensibility.1.1CoordinateFormatforSparseMatricesCoordinateformatissuitableforrepresentingsparsematrices.Onlynonzeroentriesneedbeencoded,andthecoordinatesofeacharegivenexplicitly.Thisisillustratedinthefollowingexampleofarealgeneralsparsematrix.Example1:MMcoordinateformatforarealgeneralsparsematrixConsiderthefollowing55matrix.0BBBBBB@10060010:500000:015000250:5028033:320000121CCCCCCAInMMcoordinateformatthiscouldberepresentedasfollows.%%MatrixMarketmatrixcoordinaterealgeneral%A5x5sparsematrixwith8nonzeros558111.02210.542250.5330.015146.044-280.04533.325512.0Therstlinecontainsthe%%MatrixMarketheaderfollowedbyasequenceofkeywords.Theseindicatethattheobjectbeingrepresentedisamatrixincoordinateformat,andthatthenumericdataisrepresentedinrealgeneralform.(Bygeneralwemeanthatthestorageformatisnottakingadvantageofanysymmetryproperties.)Thesecondlineisacomment.(Zeroormoresuchlinesmayappearatthispointinthele,eachbeginningwitha%.)Thenextlinecontainst