Overview

Back to Main contents.

This section presents an overview of the Jampack matrix package.

Contents

What is Jampack?
The classes of Jampack
Indexing
History
I/O

What is Jampack?

Back to: Main contents, Top of section.

Jampack (JAva Matrix PACKage) is a collection of classes and methods for manipulating matrices. It is designed to be easy for a novice to use but rich enough to meet the needs of the expert. It is reasonably efficient, although it is not in the high-performance league.

Jampack includes classes for several types of matrices (e.g., diagonal and triangular), methods implementing the common matrix operations, and methods to compute the most important matrix decompositions. The package also includes methods for generating and manipulating Householder transformations and plane rotations. A novel feature of the package is a history list that remembers decompositions that have been computed from a matrix and reuses them later.

The guiding principles of Jampack are openness and extensibility. Jampack makes no attempt to hide the implementation of its classes and methods--as if such a thing could ever be desirable in matrix computations. Instead this manual makes it easy for the user to get at the raw code of Jampack. I expect that most people will simply want to use the features of Jampack without further ado. But the significant minority with special interests or needs can get under the hood and tinker. Jampack is yours to play with--which is why this document is an owner's manual, not a user's guide.

Jampack is also open ended. Matrix operations, transformations, and functions are organized into classes of methods called suites. New features to Jampack can be added by placing new methods in the appropriate suite. It will often turn out that methods already in a suite can be used as templates to guide the coding of a new features.

The current version of Jampack is incomplete and tentative--a sort of pre-alpha job. All matrices are complex because it was felt that implementing real matrices first would cause design conflicts later. Of the full complement of matrix types--general, diagonal, band, and sparse--only general and diagonal have been implemented. The ensemble of matrix functions is incomplete--for example there is not yet a routine to compute the determinant. Many of the methods are "soft coded"; that is, they are implemented using previously coded Jampack functions instead of being written in raw Java. And the code itself is sparsely commented and lightly tested.

The main reason for releasing Jampack at this stage is to see if there is enough interest in it to justify further development. Another reason is to get people interested in contributing to the package. I hope that once a reliable core package has been established, it will continue to grow by public contributions reviewed by a Jampack supervisory committee.

The classes of Jampack

Back to: Main contents, Top of section.

The classes of Jampack fall into three broad categories: classes that define matrices, classes that manipulate matrices, and classes that generate matrix decompositions. In addition, there is a class defining complex numbers and their operations and a class defining global parameters for the package. Let's look briefly at each in turn.

Matrix classes

There are currently two matrix types implemented in Jampack--complex general matrices (Zmat) and complex diagonal matrices (Zdiagmat). (Eventually the core package will include real versions of these classes and real and complex classes for band matrices.) In addition, there are three subclasses of Zmat for upper triangular, lower triangular, and positive semidefinite matrices. These classes (called tag classes) have no constructors of their own; they exist only to allow Jampack to perform certain matrix operations efficiently--for example, the solution of linear systems.

Jampack has no vector class, but it does have a class Z1 that implements a one dimensional array of type complex. However, Z1s do not participate in the usual matrix operations.

Operation Suites

The classes for manipulating matrices are called suites. The most important suites are the ones that implement the basic matrix operations: Plus, Minus, Times, Solve, and H (for conjugate transpose). Generally a suite will have several methods. For example, the Times suite contains, among others, methods for multiplying two Zmats, multiplying a Zmat by its conjugate transpose, or multiplying a Zmat by a Zdiagmat. The generic method in any suite is named "o". For example, Times.o(A,B) will produce the product of A and B for any combination of Zmats and Zdiagmats. Special methods have longer names. For example, Times.aha(A) computes AHA.

Suites that manipulate matrices are nonaltering or altering. The methods of nonaltering suites leave their inputs unchanged. All the usual matrix operations fall in this category, as do such functions as Norm and Trace. Altering suites change their arguments. The prime examples of altering suites are Rot, which manipulates plane rotations, and House, which manipulates Householder transformations.

Decompositions

Jampack has classes implementing the six basic decompositions of matrix computations: the partially pivoted LU decomposition (Zludpp), the Cholesky decomposition (Zchol), the QR decomposition (Zqrd, Zhqrd), the Schur decomposition (Schur), the spectral decomposition of a Hermitian matrix (Zspec) and the singular value decomposition (Zsvd). In addition it has an eigenvalue-vector decomposition (Eig). For ready use, all members of a decomposition are public.

Complex numbers

Complex numbers are implemented by the class Z, which provides useful constructors and the usual operations. The operations are written in the form c.op(a,b) which causes c to be overwritten by a.op.b. This convention allows computations with Zs to proceed without the creation of new Zs, which is very important in inner loops.

Parameters

The Parameters class contains global parameters that control such things as default printing format and the base for indexing matrices.

Indexing

Back to: Main contents, Top of section.

A Zmat is implemented as two arrays of type double, one representing the real part of the matrix, the other the imaginary part. The indexing of these arrays begins at zero, as usual with Java arrays. In Jampack we say that a primitive array has a base index of zero. Matrices--as opposed to primitive arrays--usually have nonzero base indices, which vary from discipline to discipline. Consequently, Jampack allows the user to set the base index of the matrices in a Java application. To keep things from becoming too complicated, the base may be set only once per application.

History

Back to: Main contents, Top of section.

A major problem in any matrix package is to avoid the recomputation of decompositions. For example, in solving the system

Ax = b
Jampack computes (at considerable expense) an LU decomposition of A. The problem is to avoid the recomputation of the decomposition when we subsequently solve the system
Ay = c
with the same matrix A.

Jampack solves this problem by associating a history list with each matrix. When a Jampack method computes a decomposition of a matrix it may put it on the history list for later use. This procedure is surrounded by rigorous safeguards. While a decomposition is on the history list of a matrix, it is not available outside Jampack, and any alteration of the elements of a matrix causes its history list to be flushed.

I/O

Back to Main contents, Top of section.

Jampack matrices are not yet serializable, but they will be soon.

Jampack has a utility suite Print that prints primitive arrays and matrices in an appropriate format. Default parameters for the formatting are defined in the class Parameters and may be changed. They may also be specified in the Print methods themselves.