1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
|
<STYLE TYPE="text/css">
<!--
BODY
{
font-family:sans-serif;
font-size:16;
}
-->
</STYLE>
<html>
<body>
<font family="sans-serif">
<h1>SSGUI: Java interface to The SuiteSparse Matrix Collection</h1>
Tim Davis,
<a href=http://www.suitesparse.com>http://www.suitesparse.com</a>,
Texas A&M University.
<h2>1. Overview</h2>
<ul>
ssgui is a Java GUI interface to the SuiteSparse Matrix Collection at
<a href=https://sparse.tamu.edu>https://sparse.tamu.edu</a>
(formerly called the University of Florida Sparse Matrix Collection). It
provides an easy way to select matrices from the collection based on their
matrix properties. To access the collection from within MATLAB,
see ssget. This GUI can also download the *.mat files for later use in ssget.
</ul>
<h2>2. Quick Start</h2>
<ul>
First, download the ssget archive (tar.gz or zip file), and uncompress it.
Open the ssget folder.
<p>
If your web browswer requires an HTTP proxy, or if you wish to change
the download location, first see the <b>Customization</b> section below,
to configure ssgui before you run it.
<p>
To run ssgui, double-click its icon or type the following command in your
command window / terminal:
</ul>
<pre>
java -jar ssgui.jar
</pre>
<ul>
If the above command fails, then you need to install Java.
See <a href=http://www.java.com/en/download/manual.jsp>
http://www.java.com/en/download/manual.jsp</a> for details.
<p>
You can skip reading this document by simply navigating the GUI itself. Most
of the buttons, check boxes, lists, and table columns have a short "tool tip"
which is visible if you hover your mouse over the item.
<p> When the ssgui starts, it checks for any missing matrix icons and
downloads a new table if needed. This might take a few minutes, so
just sit back and enjoy the slideshow. It will only happen occassionaly.
</ul>
<h2>3. A Sparse Matrix Problem</h2>
<ul>
The SuiteSparse Matrix Collection is a simplified name. It is actually a
collection
of sparse matrix <i>problems</i>, not just sparse matrices. Each problem
includes one primary sparse matrix and meta-data about that matrix. Some
problems include additional matrices and vectors (sparse or dense) such as
right-hand-sides to a linear system <i>Ax=b</i>, or cost constraints for a
linear programming problem. As a short-hand, a "problem" in the collection is
often called simply a "matrix", refering to the primary sparse matrix in the
problem (<i>A</i>, below).
<p>
The following data is always present in any sparse matrix problem
(not all fields are shown in the table in the ssgui program, however):
<ul>
<li> <b>name</b>: the full name of the problem, in the form
<i>Group/Name</i>, where <i>Group</i> indicates the source of the
problem (a person, organization, or other collection), and <i>Name</i>
is the name of the problem within that <i>Group</i>.
<li> <b>title</b>: a short descriptive title.
<li> <b>A</b>: the primary sparse matrix itself.
It is the properties of this matrix that determine
the selection criteria.
<li> <b>id</b>: a unique serial number ranging from 1 to the number of
matrices in the collection. As new matrices are added to the
collection they are given higher id's, so new matrices are always
at the end of the table when sorted by id.
<li> <b>date</b>: the date the matrix was created, or the date it was
added to the SuiteSparse Matrix Collection if the creation date is not
known.
<li> <b>author</b>: the person or persons who created the matrix.
<li> <b>ed</b>: the person or persons to acquired the matrix from the
author and placed it in a widely accessible collection (this
one or others such as the Rutherford/Boeing collection or
the Matrix Market collection).
<li> <b>kind</b>: the domain of the problem, such as "circuit simulation",
"chemical process simulation", "finite-element problem", and so on.
</ul>
The following data is present in some problems but not all:
<ul>
<li> <b>Zeros</b>: a binary matrix holding the pattern of
entries explicitly provided by the matrix author which are equal to
zero. These may represent entries that may become nonzero later on in
a simulation, but they are equal to zero in this instance of the
matrix. Since they were provided by the matrix author(s), they are
preserved in this collection. In the MATLAB format, this matrix is
held as a different sparse matrix, since MATLAB removes explicit zeros
from its sparse matrices. In the Matrix Market and Rutherford/Boeing
collection, these entries are included in the primary sparse matrix
itself, as explicitly zero entries.
<li> <b>b</b>: the right-hand-side to a linear system or least-squares
problem. This can be a vector or matrix, real or complex, and
sparse or dense.
<li> <b>x</b>: the solution to a linear system or least-squares problem.
<li> <b>notes</b>: text, with a discussion about the problem, in no
particular format.
<li> <b>aux</b>: Any number of matrices, vectors, or text. For example, an
optimization problem may include a cost vector <i>c</i>, and vectors
that specify upper/lower bounds on the solution. Details of how to
interpret this auxiliary data are normally given in the <i>notes</i>
field. In the MATLAB format this is a struct containing each of the
items. In the Matrix Market and Rutherford/Boeing formats, this data
resides alongsize the primary matrix in a single compressed folder.
</ul>
</ul>
<h2>4. Matrix Formats</h2>
<ul>
Each matrix in the collection appears in three different formats. The data
within each format is identical, down to the very last bit (if you find a
discrepency between the same problem in different formats, please let me know).
<ul>
<li> <b>MATLAB™ *.mat file</b>. This can be loaded into MATLAB directly,
or it can be accessed via the ssget.m MATLAB interface to the collection.
Type <i>help ssget</i> in MATLAB for more details. The name of the MATLAB
file is of the form mat/Group/Name.mat (such as mat/HB/west0067.mat for the
west0067 matrix from the HB, or Harwell/Boeing, group).
<li> <b>Matrix Market *.mtx file</b> and associated files. Short meta-data
(name, title, id, date, author, ed, kind, and notes) is given as structured
comments in the primary *.mtx file. This file and any associated files (b,
x, and any aux matrices) are in a single folder which is then archived into
a *.tar.gz file. Windows users will need a 3rd-party program for handling
*.tar.gz files. For example, the Matrix Market format for the HB/west0067
matrix is held in the MM/HB/west0067.tar.gz file. See
<a href=http://math.nist.gov/MatrixMarket/index.html>
http://math.nist.gov/MatrixMarket/index.html</a>
for more information about the
Matrix Market format.
<li> <b>Rutherford/Boeing *.rb file</b> and associated files. Short meta-data
(name, title, id, date, author, ed, kind, and notes) is given as structured
comments in a separate text file. The matrix file, the informational text
file, and any associated files (b, x, and any aux matrices) are in a single
folder which is then archived into a *.tar.gz file. For example, the
Rutherford/Boeing format for the HB/west0067 file is held in the
RB/HB/west0067.tar.gz file. See
<a href=http://www.cse.scitech.ac.uk/nag/hb/>
http://www.cse.scitech.ac.uk/nag/hb/</a>
for more information about the Rutherford/Boeing format.
</ul>
</ul>
<h2>5. Selecting Matrices</h2>
<ul>
In the ssgui you are presented with four primary panels.
<p> <b>Selection Criteria panel</b>:
This is used for rule-based selections of matrix subsets. A matrix must
satisfy all properties in this panel to be selected. With the default settings
(available when the ssgui starts or after clicking <i>Reset criteria</i>) all
matrices fit the criteria. However, no matrix is selected until you press the
<i>Select</i> button or select them individually in the table by clicking the
checkbox in the <i>select</i> column.
<p> The selection criteria are based on the matrices properties described in
the matrix table (described below). To select matrices from one or more groups
and/or "kinds," click on the choices in the "group" and/or "kind" lists.
Shift-click the list to select a range of groups or kinds, and control-click
the list to add a single item to your highlighted choices. To clear your
choices, click the <i>Reset criteria</i> button, described below.
<p> When you select/deselect matrices, the boxes to the left of each matrix in
the Table of Matrices get checked/unchecked. You still see all the matrices
in the list, because you can then modify your selection by checking/unchecking
matrices one at a time in the Table itself.
<p>
At the bottom of the Selection Criteria panel is a row of buttons:
<ul>
<li> <b>Select</b>: Click this to add matrices to your selection
that fit the criteria. No matrix is removed from any prior selection.
For example, to select all square matrices with fewer than 1000 rows,
plus all complex matrices, do the following. First enter 1000 in the
top-right text field, click the <i>square</i> radio button, and then
click <i>Select</i>. Then click <i>Reset criteria</i>. Next, click
<i>complex</i> and then <i>Select</i>.
<li> <b>Deselect</b>: Click this to remove matrices from your selection
that fit the criteria. In general, if you want matrices that meet some
criteria (a) but not (b), then set the controls for (a) and click
<i>Select</i>. Next, click <i>Reset criteria</i>, set the criteria
(b), and click <i>Deselect</i>. For example, to select all square
matrices with fewer than 1000 rows that are not complex, you could just
do this with a single click of <i>Select</i> (click <i>square</i>,
<i>real</i>, and enter 1000 in the top-right text field, then click
<i>Select</i>). Alternatively, you could click <i>square</i> and enter
1000 as the upper bound on the number of rows and click <i>Select</i>
then <i>Reset criteria</i>, select <i>complex</i>, and click
<i>Deselect</i>.
<li> <b>Reset criteria</b>: This has no effect on your selection. It
simply resets the criteria to the default (all matrices). Thus, to
select all matrices, click <i>Reset criteria</i> and then
<i>Select</i>. To deselect all matrices, click <i>Reset criteria</i>
and then <i>Deselect</i>.
<li> <b>Clear selections</b>: This has no effect on your selection
criteria. It simply clears all selections, deselecting all matrices by
unchecking the <i>select</i> column in the table. This is useful if
you have a complex selection criteria and don't want to lose it by
clicking <i>Reset criteria</i>, but you wish to clear all your
selections anyway.
<li> <b>Help</b>: this button brings up the text you're reading.
</ul>
<p> <b>Matrix icon panel</b>:
To the right of the Selection Criteria panel is an icon of the most recent
matrix highlighted, downloaded, or in the process of being downloaded.
<p> <b>Table of matrices</b>:
This is a list of all the matrices in the collection. You can click on any
column header to sort the table by that column. Clicking a row (to the right
of the select column) will highlight that row. You can highlight a range of
rows by shift-clicking another row. Control-click will add individual rows.
Next, right-clicking in the table will pull up a pop-up menu allowing you to
select or deselect the highlighted matrices and to export your selection to a
file. You can export a list of your selected matrices to a comma-separarted
file (*.csv) or to a MATLAB (*.m) file. When you highlight a matrix, its icon
is displayed.
<p> The table contains the following columns (you can also hover your mouse
over each column header for a short description):
<ul>
<li><b>select</b>: whether or not you have selected the matrix.
You can click on the check boxes in this column to modify your
selection on a matrix-by-matrix basis. This is the only column in
the table that you can edit.
<li><b>mat</b>: this box is checked if you have downloaded the matrix
in its MATLAB format. The location of the HB/west0067.mat file
will be ssget/mat/HB/west0067.mat, for example.
<li><b>MM</b>: this is checked if you have already downloaded
the matrix in its Matrix Market format.
<li><b>RB</b>: this is checked if you have already downloaded
the matrix in its Rutherford/Boeing format.
<li><b>id</b>: the matrix id, in the range 1 to the number of
matrices in the collection. When the ssgui starts,
the table is sorted in this order.
<li><b>Group</b>: the group the matrix belongs to.
<li><b>Name</b>: the (short) name of the matrix. The full name of
a matrix is Group/Name.
<li><b># rows</b>: the number of rows of the matrix.
<li><b># cols</b>: the number of columns of the matrix.
<li><b># entries</b>: the number of entries in the matrix.
These include all the entries in the pattern of the matrix.
<li><b>real</b>: this box is checked if the matrix is real.
It is complex otherwise.
Note that <i>real</i> matrices include any matrix that is not
complex. In particular, integer and binary matrices are
considered <i>real</i> in this search criterion.
<li><b>binary</b>: this box is checked if the matrix is binary.
It is non-binary otherwise (there are no binary complex matrices,
so any matrix that is binary is also marked as real).
<li><b>2D/3D</b>: this box is checked if the matrix comes
from a discretization of a 2D or 3D geometry.
<li> <b>posdef</b>: this box is checked if the matrix is
symmetric and positive definite.
<li><b>psym</b>: the symmetry of the pattern of the
matrix A (including the binary <i>Zeros</i> matrix as well). Let
<i>S = pattern(pattern(A)+Zeros)</i> where <i>pattern(A)</i> is a
binary matrix with entries equal to 1 where <i>A(i,j)</i> is
an entry in the pattern of A, and zero elsewhere.
The <i>psym</i> metric is zero if the
pattern of <i>S</i> is completely unsymmetric, and 1.0 if the
pattern is exactly symmetric. Let <i>pmatched</i> be the number of
off-diagonal entries <i>S(i,j)</i> for which <i>S(i,j)=S(j,i)</i>
and let <i>pnzoffdiag</i> be the total number off-diagonal entries
in <i>S</i>. Then <i>psym</i> is the ratio
<i>pmatched/pnzoffdiag</i>.
<li><b>nsym</b>: the symmetry of the numerical values of the
matrix. This property ignores the <i>Zeros</i> matrix. It is
equal to 0 for a perfectly unsymmetric matrix, and 1.0 for a
symmetric matrix. Let <i>matched</i> be the number of nonzero
off-diagonal entries <i>A(i,j)</i> for which <i>A(i,j)=A(j,i)</i>
and let <i>nzoffdiag</i> be the total number off-diagonal nonzero
entries in <i>A</i>. Then <i>psym</i> is the ratio
<i>matched/nzoffdiag</i>.
<li><b>kind</b>: the problem domain. Note that this is typically
related to the problem group, since many matrix authors submit
matrices to the collection that arise from a single problem domain.
Some group have problems from many domains, however.
</ul>
<p> <b>Download panel</b>:
This panel controls the downloading of matrices, with
three check boxes, three buttons, and informational items:
<ul>
<li> <b>Download</b>: click this to begin the download of the
selected matrices. Matrices that are already downloaded are skipped
(thus, if one of your matrix files happens to get corrupted, simply
remove the file and restart the ssgui). Matrices are downloaded into
the <i>mat</i>, <i>MM</i>, and <i>RB</i> folders inside the ssget
folder, in the same order as they appear in the table view. For
example, if you click on the <i># entries</i> column heading prior to
clicking <i>Download</i>, your selected matrices will be downloaded in
order of increasing number of entries. If you hover your mouse
over the download button, a tool tip will tell you what it will do.
<li><b>MATLAB (mat)</b> format: click this to download the selected
matrices in MATLAB *.mat format.
<li><b>Matrix Market (MM)</b> format: click this to download the selected
matrices in Matrix Market format.
<li> <b>Rutherford/Boeing (RB)</b> format: click this to download the
selected matrices in Rutherford/Boeing format.
<li> <b>Matrices selected:</b> gives a running total of the number of
matrices selected in the table.
<li> <b>Cancel</b>: click to cancel the current download, deleting the
matrix currently being downloaded. Matrices already fully downloaded
are never deleted by the ssgui program.
<li> <b>Overall progress</b>: this progress bar advances after each
matrix is downloaded.
<li> <b>Current file</b>: this progress bar advances as the current
matrix is downloaded. The icon and name of the matrix currently
being downloaded is shown in the icon panel.
</ul>
<p> The contents of the <i>mat</i>, <i>files</i>,
<i>MM</i>, and <i>RB</i>
folders ("directories" for Unix users), and the ssstats.txt file itself,
maybe be deleted at will when the program is not running. They will be
recreated when the program restarts. If you delete the <i>files</i>
directory, for example, matrix icons are redownloaded, which makes for a
fun slide show. Sit back and watch.
</ul>
<h2>6. Customization</h2>
<ul>
The <i>ssgui.java</i> file includes five parameters
that you can modify. You can change these parameters simply by
editting ssgui.java and recompiling the file into the compiled
ssgui.jar file. Each parameter is a string.
<ul>
<li> <i>ssarchive:</i> The default folder containing the <i>mat</i>,
<i>MM</i>, <i>RB</i> and <i>files</i>
directories. It is displayed
on the GUI just above the table of matrices. The line is blank
by default. If left blank, these folders are to be found in the
current working directory. You can modify this parameter to refer to
another folder. For example, if I were to create my own folder called
<i>MyMatrices</i> in my home directory, I would use
<i>ssarchive = '/home/davis/MyMatrices/'</i> in Unix/Linux,
<i>ssarchive = '/Users/davis/MyMatrices/'</i> in Mac OS X, or
<i>ssarchive = 'C:\Documents and
Settings\davis\My Documents\MyMatrices\</i> in Windows.
Both the slash (\) and backslash (/)
characters are interpretted as your system's file-separator ('\' for
Windows, '/' for everything else).
<li> <i>sssite:</i> The root URL of the SuiteSparse Matrix Collection,
<a href=https://sparse.tamu.edu>https://sparse.tamu.edu</a>.
This only needs to change in the
event that the entire collection moves to a new URL,
or if you wish to use a mirror of the collection.
<li> <i>refresh:</i> The number of days after which a new list of matrices (in
<i>files/ssstats.csv</i> and <i>files/ss_index.mat</i>) should be
downloaded. By default this is set to 30. A value of <i>inf</i> means
that these files are never downloaded automatically. If
the <i>files/ssstats.csv</i> is missing or corrupted when ssgui starts,
it will download fresh copies of both files. Thus, to force a refresh,
simply delete the <i>files/ssstats.csv</i> file and then start ssgui.
You may also download the files with the MATLAB command
<i>ssget('refresh')</i> prior to running ssgui.
<li> <i>proxy_server:</i>
the name of your HTTP proxy server, if you connect to
the internet via a proxy. If left blank, no proxy is used.
<li><i>proxy_port:</i> the port number for your HTTP proxy. If blank,
the default of 80 is used.
</ul>
</ul>
<h2>7. Limitations and known issues</h2>
<ul>
<ul>
<li> When a download is complete, the table order jitters slightly. This is
because the <i>mat</i>, <i>MM</i>, and <i>RB</i> columns are updated. The
table sort order is temporarily modified, even if you have not currently
selected one of those columns to sort. It then returns to the proper order
immediately. This appears to be a limitation of the Java Swing library in
JDK 6.
<li> When cancelling a download with the Cancel button, or terminating the
program normally (by clicking the [x] icon to close the ssgui window), any
partial file currently being downloaded is safely deleted. These files
have the term _IN_PROGRESS appended to their name. If the ssgui program
terminates abnormally and suddenly in the middle of a download, however, it
will leave behind files of this form. You can safely delete any
*_IN_PROGRESS file when the ssgui program is not running.
<li> Working through an HTTP proxy can be sluggish, and I have even seen
downloads stall completely. If you are using a proxy and the download
stalls, try clicking <i>Cancel</i> and then <i>Download</i>. If that
fails, terminate ssgui. If you terminate it abnormally (not by clicking
the [x] in the window, but with "kill -9" in Linux, or by forcing it to
quit via your OS), you may need to delete the *_IN_PROGRESS file. Please
let me know if this happens.
</ul>
</ul>
<h2>8. Copyright and License</h2>
<ul>
ssget, Copyright (c) 2009-2022, Timothy A. Davis. All Rights Reserved.
<p>
SPDX-License-Identifier: BSD-3-clause
</ul>
<h2>9. Version and Change-Log</h2>
<ul>
<ul>
<li> See ssget/Doc/Changelog for the changes in each version.
<li>Version 2.2.0, May, 2020. Update to URL redirects.
<li>Version 2.1.0, Jan 16, 2019. Changed "# nonzeros" column to
"# entries".
<li> Version 2.0.0, Sept 3, 2017. Transition from UFgui to ssgui.
Collection renamed to the SuiteSparse Matrix Collection.
<li> When a new version of this software is available, simply move the
<i>mat</i>, <i>MM</i>, and <i>RB</i> folders from the old
<i>ssget</i> folder into the new one, to preserve the matrices you have
already downloaded.
</ul>
</ul>
<h2>10. For Further Help</h2>
<ul>
Contact the author of this ssgui program, and the maintainer of the
SuiteSparse Matrix Collection: Tim Davis
(<a href=http://www.suitesparse.com>
http://www.suitesparse.com</a>, email
<a href=mailto:DrTimothyAldenDavis@gmail.com>DrTimothyAldenDavis@gmail.com</a>).
To print this document,
open the file <i>sshelp.html</i> in your favorite web browser.
</ul>
<h2>11. Acknowledgements</h2>
<ul>
I would like to thank Iain Duff and Xiangrui Meng for their feedback,
which has improved this package. Designing a GUI is an art, and getting
usability feedback from others is vital.
</ul>
</font>
</body>
</html>
|
