API

julia MatrixDepot

Give access to a wealth of sample and test matrices and accompanying data. A set of matrices is generated locally (with arguments controlling the special case). Another set is loaded from one of the publicly accessible matrix collections SuiteSparse Matrix Collection (formerly University of Florida Matrix Collection) and the Matrix Market Collection.

Access is like

using MatrixDepot

A = matrixdepot("hilb", 10) # locally generated hilbert matrix dimensions (10,10)

A = matrixdepot("HB/1138_bus")     # named matrix of the SuiteSparse Collection
A = matrixdepot(sp(1))             # same matrix using numerical id
A = matrixdepot("Harwell*/*/1138_bus") # matrix from the Matrix Market Collection

md = mdopen("*/bfly")   # named matrix with some extra data
A = md.A
co = md.coord
tx = md("Gname_10.txt")

md = mdopen("gravity", 10, false) # locally generated example with rhs and solution
A = md.A
b = md.b
x = md.x

commands:

mdinfo, listdir, listgroups, matrixdepot, mdopen, listdata, mdlist,
metasymbols, setgroup!, deletegroup!.

selector patterns:

strings, string-patterns (using "*", "?", "[]", "/", "**"), regular expressions: for names
builtin(42), user(3,5), sp(10:11,6,2833), mm(1), mm(:): to access by integer id or all
sp(pattern), mm(pattern) to access corresponding (alternative) matrix for other collection

predicate patterns:

isboolean, isinteger, isreal, iscomplex
isgeneral, issymmetric, ishermitian, isskew
isbuiltin, isuser, islocal, isremote, isloaded, isunloaded
issvdok
keyword(string expression), logical, hasdata(symbol), @pred(expression)

see also: "logical" for logical combinations of all kinds of patterns.

matrixdepot(p::Pattern, args...)

Return matrix according to pattern or local matrix according to name and arguments.

If not loaded, load remote matrix first. p must be a unique pattern (match only one name). The presence of arguments makes sense only if the pattern matches the name of a generated (=local) matrix.

Only the matrix part is delivered, also in the local cases, where the underlying function returns a structure containing matrix and vectors. Use md = mdopen; md.A, md.b ... to access those objects.

mdopen([db,] pattern)
mdopen(f, [db,] pattern)

Return MatrixDescriptor object, which can be used with data access functions.

Make sure that data files are loaded. Keeps a cache of already delivered matrices and metadata. If the pattern has not a unique resolution, an error is thrown.

return information about all matrices selected by pattern

mdinfo()

Overview about matrices.

mdlist([db,] p::Pattern)

return a vector of full matrix names where name or alias match given pattern. p can be one of the following:

• a plain string (without characters * and ?) which must match exactly
• a string containing * and ? acting like a shell path pattern
• a regular expression
• an integer matching equivalent to the alias string "#$p"
• a range of integers
• a group name expressed as a symbol e.g. :local, :all, :illcond, :posdef
• the name of a predicate function f(::MatrixData)::Bool, e.g. issymmetric, isposdef, ...
• a vector of patterns meaning the union (or |)
• a tuple of patterns meaning the intersection ( or &)

listnames([db,] p::Pattern)

Return a formatted table of the names of all matrices matching pattern p.

listdir([db,] p::AbstractString)

list directories and the number of matrices contained in them. get an overview of the count of names down directories. return a list with summary information for directories in matrix name space. The input argument is split into 2 patterns by the first double slash "//". The whole string (with multiple slashes reduced to single slashes) determines a subset of all matrix names. They are then grouped by the first pattern and for each different group value the number of names in the subset is counted. A final / is replaced by "//**".

E.g.

• listdir("/*") - count names without a /.
• listdir("/k*") - count names without / starting with k*.
• listdir("*//*") - count names with one directory part (sp-collection)
• listdir("*/*//*") - count names with two directory parts (mm-collection)
• listdir("*//*/*") - count names with two directory parts (mm-collection)
• listdir("Har*//*/*") - restrict to directories starting with "Har"
• listdir("Har*/*//*") - all subdirectoreis of the previous

listdata([db,] p::Pattern)

Return an array of MatrixData objects according to matched patterns.

metasymbols(md::MatrixDescriptor)

Return a vector of symbols, which point to metadata of the problem. These symbols s may be used to access the objects by getproperty(md, s) or by getindex(md, s). The syntax md.S is preferred, if S is a constant Julia word. In any case md[s] is possible.

Example: md = mdopen("*/bfly"); A = md.A; co = md.coord; txt10 = md["Gname_10.txt"]

builtin(i, j:k, ...)
builtin(:)

Pattern selecting built-in (locally generated) matrices by id number.

example: mdlist(builtin(1:3))

user(i, j:k, ...)
user(:)

Pattern selecting user-defined matrix generators by id number.

sp(i, j:k, ...)
sp(pattern)

The first form with integer and integer range arguments is a pattern selecting by the id number in the Suite Sparse collection.

The second form is a pattern, which selects a matrix in the Suite Sparse collection, which corresponds to the pattern by name, even if the name is from the Matrix Market collection.

example: mdlist(sp("//1138bus")) == ["HB/1138bus"]

mm(i, j:k, ...)
mm(pattern)

The first form with integer and integer range arguments is a pattern selecting by the id number in the Matrix Market collection.

The second form is a pattern, which selects a matrix in the Matrix Market collection, which corresponds to the pattern by name, even if the name is from the Suite Sparse collection.

example: mdlist(mm("*/1138bus")) == ["Harwell-Boeing/psadmit/1138bus"]

@pred(expression)

Generate a predicate function using the expression as function body. Variable names within the expression, which are properties of RemoteMatrixData (e.g. title, m, nnz) are used to access data.title etc. Other variable names, are used from the outer scope.

example: maxnnz = 1_000; listnames(@pred(n <= maxnnz)) would produce a list of all data with less than maxnnz structural non-zeros.

keyword(word::Union{AbstractString,Tuple,Vector})

Predicate function checks, if word is contained in on to the textual metadata fields [:notes, :title, :kind, :author]. Tuples and Vectors are interpreted as AND resp. OR.

hasdata(meta::Union{Symbol,Tuple,Vector})

Predicate function checks, if matrix data have metadata symbol meta. Tuples and Vectors are interpreted as AND resp. OR.

Pattern syntactic sugar

the logical operators |, &, and ~ may be applied to all kind of Patterns with the usual meaning.

• ~ : unary negation operator - pattern does not match (highest priority)

• & : binary logical and - both patterns match

• | : binary logical or - any of the pattern match (lowest priority)

• parentheses can be used to overrule operator precedence.

• [p...] is the same as p[1] | p[2] ...

• (p...) is the same as p[1] & p[2] ...

• ~(p...) === ~((p...)) - that is ~(p[1] & p[2] ...)

• Precedence of '*' is higher that ~ for character and string objects:

so ~ "a" * "b" === ~("a" * "b") === ~"ab" also ~'a'^2*"b" === ~"aab"

charfun(p::Pattern)

Return the characteristic function corresponding to the set-defining pattern p.

This function can be applied to objects data::MatrixData and strings, the canonical names of those objects.

listgroups()

Return a list of available groups (array of Symbol).

setgroup!(s::Symbol, p::Pattern)

Define user group. s must not be one of the predefined group names. p may be any pattern, also a vector of matrix names.

deletegroup!(s::Symbol)

Delete a previously defined user group.

load([db,] pattern)

Load data from remote repository for all problems matching pattern.

Return the number of successfully loaded matrices.

loadinfo([db,] pattern)

loadinfo(data::RemoteDate)

Download the first part of the data file. Stop reading, as soon as the initial comment and the size values of the main matrix have been finished. Store this in a file with extension .info in the same directory, where the .mtx file is. If the complete file is already available, the download is not performed, because the head of the .mtx file contains the same lines.

loadsvd([db,], pattern)

loadsvd(data::RemoteMatrixData)

Download the extra information related to SVD from the backing repository. That is currently the TAMU site for the UFl collection. The files are in MAT format, and are uncompressed and un-tar-ed if necessary.

add a group to Matrix Depot

add or replace group in Matrix Depot

remove an added group from Matrix Depot