SuiteSparseCollection, Copyright (c) 2006-2019, Timothy A Davis.
All Rights Reserved.
SPDX-License-Identifier: GPL-2.0+

SuiteSparseCollection is a MATLAB toolbox for managing the SuiteSparse Matrix
Collection.  If you are a MATLAB user of the collection, you would not normally
need to use this toolbox.  It contains code for creating the index for the
collection (the ss_index.mat file in the ssget package), for creating the web
pages for the collection, and creating the Matrix Market and Rutherford/Boeing
versions of the matrices.  This code is posted here primarily so that users of
the collection can see how the matrices and their statistics were generated.

This software (ssread, specifically) also allows the user to keep a single copy
of the collection for use both inside MATLAB and outside MATLAB.  The MM/ and
RB/ versions of the collection can be read into MATLAB via ssread, even without
explicitly extracting the tar files.  They can also be read by non-MATLAB
programs.  ssread is much slower than ssget, however.

--------------------------------------------------------------------------------
MATLAB help for the SuiteSparseCollection toolbox:
--------------------------------------------------------------------------------

SuiteSparseCollection: software for managing the SuiteSparse Matrix Collection

  To create the index:

    ssindex    - create the index for the SuiteSparse Matrix Collection
    ssstats    - compute matrix statistics for the SuiteSparse Matrix Collection

  To create images for the web pages:

    ssgplot    - draw a plot of the graph of a sparse matrix
    ssint      - print an integer to a string, adding commas every 3 digits
    sslocation - URL and top-level directory of SuiteSparse Matrix Collection
    sspage     - create images for a matrix in SuiteSparse Matrix Collection
    sspages    - create images for matrices SuiteSparse Matrix Collection
    dsxy2figxy - Transform point or position from axis to figure coords

  To create the Matrix Market and Rutherford/Boeing versions of the collection:

    ssexport     - export to Matrix Market and Rutherford/Boeing formats
    ssread       - read a Problem in Matrix Market or Rutherford/Boeing format
    sswrite      - write a Problem in Matrix Market or Rutherford/Boeing format
    ssfull_read  - read a full matrix using a subset of Matrix Market format
    ssfull_write - write a full matrix using a subset of Matrix Market format

  Requires ssget, CSparse, CHOLMOD, AMD, COLAMD, RBio, and METIS.


--------------------------------------------------------------------------------
Files:
--------------------------------------------------------------------------------

    Doc/ChangeLog           changes to the package
    Contents.m		    MATLAB help
    dsxy2figxy.m	    convert XY points for plot annotations
    README.txt		    this file
    ssexport.m		    export to MM and RB
    ss_install.m            installation
    ssfull_read.m	    read a full matrix
    ssfull_write.c	    write a full matrix
    ssfull_write.m	    MATLAB help for ssfull_write
    ssgplot.m		    plot a graph
    ssindex.m		    create ss_index.mat
    sslocation.m	    URL and directory for the collection
    sspage.m		    create a web page for a matrix
    sspages.m		    create web pages for all matrices
    ssread.m		    read a Problem
    ssstats.m		    compute statistics about a matrix
    sswrite.m		    write a Problem

See MATLAB_Tools/Doc/License.txt for the license

--------------------------------------------------------------------------------
To add a matrix to the collection:
--------------------------------------------------------------------------------

These instructions are for the maintainer of the collection (that is, just
notes to myself), but they also indicate how the above software is used.
Requires most of SuiteSparse (ssget, CHOLMOD, AMD, COLAMD, CSparse, RBio, and
SuiteSparseCollection), and METIS.

The location of the primary archive of the collection is
backslash.cse.tamu.edu:/archive/davis/SuiteSparseCollection,
which is only accessible to the maintainers of the collection.

A local copy of ssget should be installed where the mat, MM, RB, and svd
directories are replaced with symbolic links to the directories in
backslash.cse.tamu.edu:/archive/davis/SuiteSparseCollection.  The
ssget/files directory should not be a symbolic link.

1) Get the matrix into MATLAB (method depending on how the matrix was
    submitted).  Use load and sparse2, RBread, mread, or specialized code
    written just for that matrix.

2) Add the full matrix name to the end of the file:
    backslash:/archive/davis/SuiteSparseCollection/files/ss_listing.txt
    Each line in the file has the form Group/Name.  The line number in
    ss_listing.txt must match the matrix Problem.id number, and full name
    must match the Problem.name in the MATLAB struct.

3) Create a new directory
    backslash:/archive/davis/SuiteSparseCollection/mat/Group,
    where Group is the new matrix group.  Add a README.txt file to this
    directory, the first line of which is a one-line summary that will appear
    in the top-level web page for the collection.  Skip this step if adding a
    matrix to an existing group.

4) Create the Problem struct; type "help sswrite" for details.  Required fields:

    Problem.name    full name of the matrix (Group/Name)
    Problem.title   short descriptive title
    Problem.A	    the sparse matrix
    Problem.id	    integer line number in ss_listing.txt
    Problem.date    date the matrix was created, or added to the collection
    Problem.author  matrix author
    Problem.ed	    matrix editor/collector
    Problem.kind    a string.  For a description, see below.

    optional fields:

    Problem.Zeros   binary pattern of explicit zero entries
    Problem.b	    right-hand-side
    Problem.x	    solution
    Problem.notes   a char array
    Problem.aux	    auxiliary matrices (contents are problem dependent)

    Save to a MATLAB mat-file.  In the mat directory, do this in MATLAB:

    save (Problem.name, 'Problem', '-v7') ;

    or for very large problems (ids 1903 and 1905, for example):

    save (Problem.name, 'Problem', '-v7.3') ;

    Move the new *.mat files into
    backslash:/raid/SuiteSparseCollection/html//mat/Group.

5) Compute matrix statistics and extend the ss_index. Do this in MATLAB:

    ssindex (ids)

    where ids is a list of the new matrix id's.  Updated ss_index.mat and
    ssstats.csv files are placed in the current working directory.
    Move the new ss_index.mat and ssstats.csv files to 
    backslash:/archive/davis/SuiteSparseCollection/files,
    overwriting the old copies there.  Also copy them into
    [path to ssget]/files/ so they will be found by the MATLAB ssget.m.

6) Export the matrix in Matrix Market and Rutherford/Boeing formats.

    ssexport (ids)

    or

    ssexport (ids, 'check')

    then tar and compress the resulting MM/Group/Name and RB/Group/Name
    directories, one per Problem (if ssexport has not already done so).  The
    2nd option with 'check' is slower, but it reads back in the created MM and
    RB formats and ensures they are identical to the MATLAB *.mat files.
    The tar files can be too big for MATLAB so they must be tar.gz'ed
    manually with:

        tar -v -cf - $problem | gzip -9 > $problem.tar.gz

    where $problem is a single problem folder, such as MM/HB/west0067.
    This creates the MM/HB/west0067.tar.gz file.

7) Create the images for the web pages:

    sspages (ids)

8) Make the collection world-readable.  In 
    backslash:/archive/davis/SuiteSparseCollection/ do:

    chmod -R og+rX mat files MM RB

9) reconstruct the sparse.tamu.edu web pages to include the new matrices

--------------------------------------------------------------------------------
Problem.kind
--------------------------------------------------------------------------------

Problems with 2D/3D geometry

    2D/3D problem
    acoustics problem
    computational fluid dynamics problem
    computer graphics/vision problem
    electromagnetics problem
    materials problem
    model reduction problem
    robotics problem
    semiconductor device problem
    structural problem
    thermal problem 

Problems that normally do not have 2D/3D geometry

    chemical process simulation problem
    circuit simulation problem
    counter-example problem: Some of these may have 2D/3D geometry.
    economic problem
    frequency-domain circuit simulation problem
    least squares problem
    linear programming problem
    optimization problem
    power network problem
    statistical/mathematical problem
    theoretical/quantum chemistry problem
    combinatorial problem

Graph problems

    This problem includes the graph or multigraph keyword. It is a network or
    graph. A graph may or may not have 2D/3D geometry (typically it does not).
    Several secondary phrases can be included in Problem.kind:

        directed or undirected: A graph is either directed, undirected, or
        bipartite. (bipartite graphs are always undirected). If not bipartite,
        the matrix will always be square. Unsymmetric permutations of the
        matrix have no meaning. If directed, the edge (i,j) is not the same as
        (j,i), and the matrix will normally be unsymmetric. If undirected, the
        edges (i,j) and (j,i) are the same, and the matrix is always symmetric.

        weighted: If the graph has edge weights, this word will appear. The
        edge weight of edge (i,j) is the value of A(i,j). This phrase is used
        for a graph only, never for a multigraph. If the graph is not weighted,
        the matrix is binary.

        bipartite: If the rows and columns of the matrix reflect different sets
        of nodes. The matrix A is normally rectangular, but can be square. Any
        permutation (unsymmetric or symmetric) of the matrix is meaningful.

        random: This Problem has been randomly generated. It is included in the
        SuiteSparse Matrix Collection only because it has been used as a
        standard benchmark. Randomly generated problems are otherwise excluded
        from the collection.  multigraph or graph: If the matrix represents a
        multigraph, then A(i,j) reflects the number of edges (i,j). The edges
        themselves are always unweighted. If the matrix represents a graph,
        then A(i,j) is either 0 or 1 for an unweighted graph, or the weight of
        edge (i,j) otherwise. 

        temporal:  If the edges have time stamps.  The edges are usually
        held in Problem.aux.temporal_edges, an e-by-3 or by-4 dense matrix,
        if there are e temporal edges.  Each row is a single edge, with
        [source target time] or [source target weight time].

        multigraph:  If there can be multiple edges (i,j) in the graph.
        If the graph is unweighted, then A(i,j) is the number of (i,j) edges.

