# 5. Jacobi’s Method

. By Eugene McDonnell. First published in Vector, 11, 3, (January 1995), 111-118.

### Parallel Jacobi

Warning: this column contains material which may either put you to sleep or turn you against applied mathematics altogether. To take some of the sting away I have added a problem which may give you some pleasure in trying to solve. If you completely distrust your ability to read descriptions of programs, no matter how well-written, I advise you to go at once to the section headed “Problem” and avoid the preliminary exposition, or the material following, valuable as it is.

### Background

Recently I had need of a program to perform eigenanalyses of square symmetric matrices, and went to Vector 9, 3, January 1993, which had Donald !McIntyre’s article “Jacobi’s Method for Eigenvalues: an Illustration of J”. I refer you to that article for !McIntyre’s lucid explanation of what the method is. In the course of transcribing his 11-line Jacobi program, along with its sixteen subprograms and its seven utility verbs, I thought I saw the possibility of speeding it up significantly by taking advantage of some of the parallelism inherent in the problem. I have communicated with McIntyre concerning this, and he tells me that he has used this method for many years, beginning with a Fortran program which he obtained from someone many years ago, transcribing it into APL and recently, as his article shows, into J.

If you look at his program, you will see that at the heart of it are the lines

```   r=. ((cos,-sin),sin,cos) (ia R)} I
Q=. q ip |:r [ R=. r ip R ip |:r
```

The first line amends an identity matrix conforming to the argument matrix by replacing two of its diagonal elements and the two corresponding off-diagonal elements with a 2-by-2 rotation matrix. The elements amended are chosen by finding the off-diagonal element of maximum magnitude, say at row-column indices p,q, and inserting the 2-by-2 matrix items at locations (p,p), (p,q), (q,p) and (q,q). This amended identity matrix r is then used with two matrix products involving R, the original argument, and Q, originally an identity matrix. Those involving R have the effect of zeroing out elements (p,q) and (q,p) of R, while leaving the eigenvalues of R unaltered. When this operation has been performed a sufficient number of times, one finds that all of the off-diagonal elements are essentially zero, and that the diagonal elements are the eigenvalues of the argument matrix. Those involving Q produce the eigenvectors of the argument matrix.

The valuable book Matrix Computations by Golub and Van Loan describes this method (section 8.5), but because the search for (p,q) is O(n^2^), goes on to suggest that it might be more efficient to select p and q in a more rigid way. For the case of a 4-by-4 argument, they suggest that p and q be selected in the following order:

```   p   q
0   1
0   2
0   3
1   2
1   3
2   3
```

and go back to the beginning, repeating until a sufficiently good solution appears. Golub and Van Loan go on to point out that the rows of the (p,q) table can be arranged in a disjoint, or non-conflicting fashion:

```     a           b           c
0   1       0   2       0   3
2   3       1   3       1   2
```

and that, in a parallel machine, separate processors can be assigned to perform the individual matrix product operations. For example, in the 4-by-4 case, two processors are needed, so that in step A one processor could do the (0,1) case and the other processor could do the (2,3) case; in step B one processor could do the (0,2) case and the other processor could do the (1,3) case; and similarly for step C. They point out that this method works only for even-order matrices, but that the odd case can be handled by bordering the argument matrix on the right and at the bottom with zeros, and then dropping these excess columns at the end. Thus the rotation matrices needed would look like this:

```        step A         |       step B      |       step C
c01  s01   0    0 | c02   0   s02   0 | c03   0    0   s03
-s01  c01   0    0 |  0    0    0    0 |  0    0    0    0
proc1 0    0    0    0 |-s02   0   c02   0 |  0    0    0    0
0    0    0    0 |  0    0    0    0 |-s03   0    0   c03
0    0    0    0 |  0    0    0    0 |  0    0    0    0
0    0    0    0 |  0   c13   0   s13|  0   c12  s12   0
proc2 0    0   c23  s23|  0    0    0    0 |  0  -s12  c12   0
0    0  -s23  c23|  0  -s13   0   c13|  0    0    0    0
```

My contribution enters here. I realized that one doesn’t need a parallel machine to obtain the benefits of this parallel Jacobi method. One can combine the rotation matrices, since they are disjunct, as follows:

```      step A       |      step B       |       step C
c01  s01   0    0 | c02   0   s02   0 | c03   0    0   s03
-s01  c01   0    0 |  0   c13   0   s13|  0   c12  s12   0
0    0   c23  s23|-s02   0   c02   0 |  0  -s12  c12   0
0    0  -s23  c23|  0  -s13   0   c13|-s03   0    0   c03
```

This technique reduces the number of matrix products required for a matrix of size n by a factor of n%2. Thus the larger the matrix, the greater the savings. A 10-by-10 problem can be reduced by a factor of 5; a 100-by-100 problem by a factor of 50, and so forth.

### The Problem

Now we come to the playful part. As you can see, the row-column pairs to be included at each step must somehow be derived. In the case of a 4-by-4 matrix, we see that step A uses the pairs (0 1) and (2 3); step B uses (0 2) and (1 3); and step C uses (0 3) and (1 2). The problem is to determine a permutation z that produces the desired result. For example, for n=4 any of the following permutations will do:

```  0 2 3 1
0 3 1 2
1 2 0 3
1 3 2 0
2 0 1 3
2 1 3 0
3 0 2 1
3 1 0 2
```

If we set z=: 0 3 1 2, we can experiment as follows:

```   ] a=: (z&{)^:(i. <:#z) i. #z   NB. all of the possible permutations
0 1 2 3
0 3 1 2
0 2 3 1

] b=: ((2!#z),2)\$,a    NB. exhibit all the pairs of items
0 1
2 3
0 3
1 2
0 2
3 1

] c=: (>/"1)b          NB. mask shows where lead item is greater than trail
0 0 0 0 0 1

] d=: c |."_1 b        NB. pairs with leading smaller item
0 1
2 3
0 3
1 2
0 2
1 3

] e=: /:~d             NB. pairs in ascending order
0 1
0 2
0 3
1 2
1 3
2 3
```

Problem 1: Define a verb which takes as argument a positive even integer n and yields a permutation which, repeatedly applied to a conforming identity permutation, produces, in successive pairs of items, all possible choices of 2 items from n, with no duplications.

Problem 2: How many of the !n permutations of even order n are solutions to problem 1?*

### Principal verbs

The verbs described below were written for J8. If you are using an earlier version of J you may wish to get your system upgraded. Here are the verbs making up my solution to the parallel Jacobi problem. The two verbs CEA and CEAI produce identical results, but CEA is written using the rhetorical control structures which have been added to J recently (see my last article) and CEAI uses the algebraic control structures which have been in J from the beginning.

Each main verb CEA and CEAI (Complete EigenAnalysis) takes as argument a square symmetric matrix A and returns two conforming matrices, the first with the eigenvalues along the diagonal, and zeros elsewhere, and the second whose columns are the eigenvectors for the corresponding eigenvalues. They each test the parity of the number of rows of A. If this is even they laminate to A a conforming identity matrix, using the utility verb IM, and then apply the subverb PJ to this initial argument. If it is odd, the action is to border A on the right and the bottom with a column and row of zeros, using the utility verb bz, and then to apply CEA (or CEAI) to this, and at the end removing the bottom row and rightmost column of each matrix of the result with the utility verb ub.

```CEA =: 3 : 'if. (2|#y) do. ub"2 CEA bz y else. PJ y,:IM y end.'
CEAI=: (PJ@(,:IM))`(ub"2@(CEAI@bz))@.(2:|#)
```

The subverb PJ (parallel Jacobi) takes as argument an array of two square matrices. It prepares four global variables for use by hsjr: a quantity eps as the product of a globally defined tolerance tol and the Frobenius norm of the first matrix, yielded by the utility verb NF; a quantity s, the number of rows in the first square matrix; a list k, the integers from 0 to s-1; and a list p, a permutation which will be used to alter the arrangement of the atoms of k, using the utility verb mxp. It then employs the verb hsjr (half of s Jacobi rotations) to the limit. At the limit, it yields the desired complete eigenanalysis of the original argument.

```PJ=: 3 : 0
eps=: tol*NF {. y
s=: # {. y
k=: i. s
p=: mxp s
hsjr ^:_ y
)
```

The subverb hsjr (half of s Jacobi rotations) takes as argument an array of two square matrices. It begins by making a rotation matrix rm, using the verb RM. This rotation matrix is used with the first matrix of the argument to develop PJ0, the next stage of the eigenvalue matrix, one which has a smaller off-diagonal norm than the previous one, and setting to zero any of its elements which are less than or equal to the quantity eps, using the utility verb clean. Next, it uses the same rotation matrix rm with the last matrix of the argument, to develop PJ1, the next stage in the eigenvector matrix. The two matrices are laminated to give the result array.

```hsjr=: 3 : 0
rm=. (k=:p{k) RM {.y
PJ0=. ((|:rm)+/ .*({.y)+/ .*rm) clean eps
PJ1=. ({:y)+/ .*rm
PJ0,:PJ1
)
```

The subverb RM (rotation matrix) builds a parallel Jacobi rotation matrix.

It takes as left argument a particular permutation of the integers from 0 through sP1. It fashions this into a two-column table t, then reverses those rows of t in which the first atom is greater than the second atom. An array cs of 2-by-2 cosine-sine matrices, one for each row of t, is formed, using the verb csm. These will be used to amend a matrix of zeros in locations specified by a conforming array of 2-by-2 boxes ix, whose atoms are each a 2-atom list derived from the corresponding row of t, formed using the utility verb CP (Cartesian product).

For example, if a row of t is 2 3, the 2-by-2 boxes corresponding to it will be:

```    +---+---+
|2 2|2 3|
+---+---+
|3 2|3 3|
+---+---+
```

Finally, a matrix of zeros is formed, conforming to the right argument y, and the positions in this corresponding to positions given by the matrices of ix will be amended with the corresponding matrices of cs, yielding the desired parallel Jacobi rotation matrix.

```RM=: 4 : 0
t=. ((-:s),2)\$x
t=. (>/"1 t)|."0 1 t
cs=. y csm"2 1 t
ix=. CP t
cs ix}0:"0 y
)
```

The subverb csm (cosine-sine matrix) takes as left argument a square matrix and as right argument a 2-element list of indices for that matrix, the first element giving a row number and the second element giving a column number, with the row number less than the column number. If the entry in the matrix at that row-column position is zero, the result will be a 2-by-2 identity matrix. If it is nonzero the result will be a 2-by-2 Jacobi rotation matrix, using the verb makecs.

```csm=: makecs`(=@(i.@2:))@.(0:=<@]{[)
```

The subverb makecs (make cosine-sine table) takes as left argument a square matrix and as right argument a 2-element list of indices for that matrix, the first element giving a row number and the second element giving a column number, with the row number less than the column number. It yields a 2-by-2 Jacobi rotation matrix.

```makecs=: 4 : 0
tau=. (((<2#}. y){x)-(<2#{. y){x)%+:(<y){x
t=. (*tau)%(|tau)+4 o. tau
c=. %4 o. t
s=. t*c
(c,s),:(-s),c
)
```

The subverb mxp (make index permutation) takes a positive even integer as argument and yields a list which is a permutation of the integers from 0 through one less than the argument. The permutation is such that when applied repeatedly to a conforming list, none of the successive pairs in the lists are equal.

```mxp=: [: C. 1 0 ; <:@(,~ >:@|.)@>:@+:@i.@-:
```

### Utility verbs

The utility verb CP takes a list as argument and returns the Cartesian product of the items of the list.

```CP=: {@;"1~
```

The utility verb IM takes as argument a matrix and yields an identity matrix having the same number of rows.

```IM=: [: = [: i. #
```

The utility verb NF takes a matrix argument and yields its Frobenius norm as result.

```NF=: [: %: [: +/ [: , *:
```

The utility verb clean takes a numeric array as left argument and a positive atom as right argument. It yields a conforming array as result, wherein each element of the left argument with magnitude less than the right argument is replaced by zero.

```clean=: [ * ] < [: | [
```

The utility verb bz takes a matrix argument and yields a similar matrix bordered on the right and below by a new column and row of zeros.

```bz=: >:@\$ {. ]
```

The utility verb ub takes a matrix argument and yields a similar matrix with the rightmost column and bottom row removed.

```ub=: _1 _1&}.
```

### Test Information

Alter the following value as desired to control accuracy and speed:

```   tol=: 1e_6  NB. value should be in the range 1e_2 to 1e_17

NB. Test matrices

] A=: 1 1 1 1,1 2 3 4,1 3 6 10,:1 4 10 20
1 1  1  1
1 2  3  4
1 3  6 10
1 4 10 20

] m=: 1.5 _1 _0.5,_1 2 _1,:_0.5 _1 1.5
1.5 _1 _0.5
_1  2   _1
_0.5 _1  1.5

] r=: 1 1 0.5,1 1 0.25,:0.5 0.25 2
1    1  0.5
1    1 0.25
0.5 0.25    2

NB. test results, using tol as specified above

CEA A
0.453835         0         0         0
0  0.038016         0         0
0         0   2.20345         0
0         0         0   26.3047

0.787275 _0.308686  0.530366 0.0601868
_0.163234  0.723091  0.640331  0.201173
_0.532107  _0.59455  0.391833  0.458082
0.265358  0.168411 _0.393897  0.863752

CEA m
2         0       0
0         3       0
0         0       0

0.707107 _0.408248 0.57735
_9.88291e_10  0.816497 0.57735
_0.707107 _0.408248 0.57735

CEA r
_0.0166473         0        0
0   1.48012        0
0         0  2.53653

0.721208   0.44428 0.531483
_0.686348   0.56211 0.461473
_0.093729 _0.697601 0.710329
```

### Solutions to Problems

Solutions provided by RogerHui

Solution to Problem 1:

```   magicperm=: C. @ < @ (|.@:>: , }.) @ (i.&.-:)
magicperm 2
0 1
magicperm 4
0 2 3 1
magicperm 6
0 2 4 1 5 3
magicperm 8
0 2 4 1 6 3 7 5
```

Solution to Problem 2:

```  seq  =: 3 : 'y {^:(}:i.#y) i.#y'
pairs=: [: /:~ _2 /:~\ ,@seq
+/ (2 comb n)&-:@pairs@(A.&(i.n))"0 i.!n=: 2
2
+/ (2 comb n)&-:@pairs@(A.&(i.n))"0 i.!n=: 4
8
+/ (2 comb n)&-:@pairs@(A.&(i.n))"0 i.!n=: 6
48
...
```

### Reference

The article referred to at the beginning of this essay, Jacobi's Method for Eigenvalues: an Illustration of J, is available as a scanned image with some of the code also available in text files. However, the J language has changed sufficiently since that time that the top-level function "jacobi" will not work without substantial modification.