JAL-2403 redundant 'implements' removed
[jalview.git] / src / jalview / math / Matrix.java
1 /*
2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
4  * 
5  * This file is part of Jalview.
6  * 
7  * Jalview is free software: you can redistribute it and/or
8  * modify it under the terms of the GNU General Public License 
9  * as published by the Free Software Foundation, either version 3
10  * of the License, or (at your option) any later version.
11  *  
12  * Jalview is distributed in the hope that it will be useful, but 
13  * WITHOUT ANY WARRANTY; without even the implied warranty 
14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR 
15  * PURPOSE.  See the GNU General Public License for more details.
16  * 
17  * You should have received a copy of the GNU General Public License
18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
19  * The Jalview Authors are detailed in the 'AUTHORS' file.
20  */
21 package jalview.math;
22
23 import jalview.util.Format;
24 import jalview.util.MessageManager;
25
26 import java.io.PrintStream;
27
28 /**
29  * A class to model rectangular matrices of double values and operations on them
30  */
31 public class Matrix
32 {
33   /*
34    * the cell values in row-major order
35    */
36   public double[][] value;
37
38   /*
39    * the number of rows
40    */
41   public int rows;
42
43   /*
44    * the number of columns
45    */
46   public int cols;
47
48   /** DOCUMENT ME!! */
49   public double[] d; // Diagonal
50
51   /** DOCUMENT ME!! */
52   public double[] e; // off diagonal
53
54   /**
55    * maximum number of iterations for tqli
56    * 
57    */
58   int maxIter = 45; // fudge - add 15 iterations, just in case
59
60   /**
61    * Creates a new Matrix object. For example
62    * 
63    * <pre>
64    *   new Matrix(new double[][] {{2, 3, 4}, {5, 6, 7})
65    * constructs
66    *   (2 3 4)
67    *   (5 6 7)
68    * </pre>
69    * 
70    * Note that ragged arrays (with not all rows, or columns, of the same
71    * length), are not supported by this class. They can be constructed, but
72    * results of operations on them are undefined and may throw exceptions.
73    * 
74    * @param values
75    *          the matrix values in row-major order
76    */
77   public Matrix(double[][] values)
78   {
79     this.rows = values.length;
80     this.cols = this.rows == 0 ? 0 : values[0].length;
81     this.value = values;
82   }
83
84   /**
85    * Returns a new matrix which is the transposes of this one
86    * 
87    * @return DOCUMENT ME!
88    */
89   public Matrix transpose()
90   {
91     double[][] out = new double[cols][rows];
92
93     for (int i = 0; i < cols; i++)
94     {
95       for (int j = 0; j < rows; j++)
96       {
97         out[i][j] = value[j][i];
98       }
99     }
100
101     return new Matrix(out);
102   }
103
104   /**
105    * DOCUMENT ME!
106    * 
107    * @param ps
108    *          DOCUMENT ME!
109    */
110   public void print(PrintStream ps)
111   {
112     for (int i = 0; i < rows; i++)
113     {
114       for (int j = 0; j < cols; j++)
115       {
116         Format.print(ps, "%8.2f", value[i][j]);
117       }
118
119       ps.println();
120     }
121   }
122
123   /**
124    * Returns a new matrix which is the result of premultiplying this matrix by
125    * the supplied argument. If this of size AxB (A rows and B columns), and the
126    * argument is CxA (C rows and A columns), the result is of size CxB.
127    * 
128    * @param in
129    * 
130    * @return
131    * @throws IllegalArgumentException
132    *           if the number of columns in the pre-multiplier is not equal to
133    *           the number of rows in the multiplicand (this)
134    */
135   public Matrix preMultiply(Matrix in)
136   {
137     if (in.cols != this.rows)
138     {
139       throw new IllegalArgumentException("Can't pre-multiply " + this.rows
140               + " rows by " + in.cols + " columns");
141     }
142     double[][] tmp = new double[in.rows][this.cols];
143
144     for (int i = 0; i < in.rows; i++)
145     {
146       for (int j = 0; j < this.cols; j++)
147       {
148         tmp[i][j] = 0.0;
149
150         for (int k = 0; k < in.cols; k++)
151         {
152           tmp[i][j] += (in.value[i][k] * this.value[k][j]);
153         }
154       }
155     }
156
157     return new Matrix(tmp);
158   }
159
160   /**
161    * 
162    * @param in
163    * 
164    * @return
165    */
166   public double[] vectorPostMultiply(double[] in)
167   {
168     double[] out = new double[in.length];
169
170     for (int i = 0; i < in.length; i++)
171     {
172       out[i] = 0.0;
173
174       for (int k = 0; k < in.length; k++)
175       {
176         out[i] += (value[i][k] * in[k]);
177       }
178     }
179
180     return out;
181   }
182
183   /**
184    * Returns a new matrix which is the result of postmultiplying this matrix by
185    * the supplied argument. If this of size AxB (A rows and B columns), and the
186    * argument is BxC (B rows and C columns), the result is of size AxC.
187    * <p>
188    * This method simply returns the result of in.preMultiply(this)
189    * 
190    * @param in
191    * 
192    * @return
193    * @throws IllegalArgumentException
194    *           if the number of rows in the post-multiplier is not equal to the
195    *           number of columns in the multiplicand (this)
196    * @see #preMultiply(Matrix)
197    */
198   public Matrix postMultiply(Matrix in)
199   {
200     if (in.rows != this.cols)
201     {
202       throw new IllegalArgumentException("Can't post-multiply " + this.cols
203               + " columns by " + in.rows + " rows");
204     }
205     return in.preMultiply(this);
206   }
207
208   /**
209    * Answers a new matrix with a copy of the values in this one
210    * 
211    * @return
212    */
213   public Matrix copy()
214   {
215     double[][] newmat = new double[rows][cols];
216
217     for (int i = 0; i < rows; i++)
218     {
219       System.arraycopy(value[i], 0, newmat[i], 0, value[i].length);
220     }
221
222     return new Matrix(newmat);
223   }
224
225   /**
226    * DOCUMENT ME!
227    */
228   public void tred()
229   {
230     int n = rows;
231     int l;
232     int k;
233     int j;
234     int i;
235
236     double scale;
237     double hh;
238     double h;
239     double g;
240     double f;
241
242     this.d = new double[rows];
243     this.e = new double[rows];
244
245     for (i = n; i >= 2; i--)
246     {
247       l = i - 1;
248       h = 0.0;
249       scale = 0.0;
250
251       if (l > 1)
252       {
253         for (k = 1; k <= l; k++)
254         {
255           scale += Math.abs(value[i - 1][k - 1]);
256         }
257
258         if (scale == 0.0)
259         {
260           e[i - 1] = value[i - 1][l - 1];
261         }
262         else
263         {
264           for (k = 1; k <= l; k++)
265           {
266             value[i - 1][k - 1] /= scale;
267             h += (value[i - 1][k - 1] * value[i - 1][k - 1]);
268           }
269
270           f = value[i - 1][l - 1];
271
272           if (f > 0)
273           {
274             g = -1.0 * Math.sqrt(h);
275           }
276           else
277           {
278             g = Math.sqrt(h);
279           }
280
281           e[i - 1] = scale * g;
282           h -= (f * g);
283           value[i - 1][l - 1] = f - g;
284           f = 0.0;
285
286           for (j = 1; j <= l; j++)
287           {
288             value[j - 1][i - 1] = value[i - 1][j - 1] / h;
289             g = 0.0;
290
291             for (k = 1; k <= j; k++)
292             {
293               g += (value[j - 1][k - 1] * value[i - 1][k - 1]);
294             }
295
296             for (k = j + 1; k <= l; k++)
297             {
298               g += (value[k - 1][j - 1] * value[i - 1][k - 1]);
299             }
300
301             e[j - 1] = g / h;
302             f += (e[j - 1] * value[i - 1][j - 1]);
303           }
304
305           hh = f / (h + h);
306
307           for (j = 1; j <= l; j++)
308           {
309             f = value[i - 1][j - 1];
310             g = e[j - 1] - (hh * f);
311             e[j - 1] = g;
312
313             for (k = 1; k <= j; k++)
314             {
315               value[j - 1][k - 1] -= ((f * e[k - 1]) + (g * value[i - 1][k - 1]));
316             }
317           }
318         }
319       }
320       else
321       {
322         e[i - 1] = value[i - 1][l - 1];
323       }
324
325       d[i - 1] = h;
326     }
327
328     d[0] = 0.0;
329     e[0] = 0.0;
330
331     for (i = 1; i <= n; i++)
332     {
333       l = i - 1;
334
335       if (d[i - 1] != 0.0)
336       {
337         for (j = 1; j <= l; j++)
338         {
339           g = 0.0;
340
341           for (k = 1; k <= l; k++)
342           {
343             g += (value[i - 1][k - 1] * value[k - 1][j - 1]);
344           }
345
346           for (k = 1; k <= l; k++)
347           {
348             value[k - 1][j - 1] -= (g * value[k - 1][i - 1]);
349           }
350         }
351       }
352
353       d[i - 1] = value[i - 1][i - 1];
354       value[i - 1][i - 1] = 1.0;
355
356       for (j = 1; j <= l; j++)
357       {
358         value[j - 1][i - 1] = 0.0;
359         value[i - 1][j - 1] = 0.0;
360       }
361     }
362   }
363
364   /**
365    * DOCUMENT ME!
366    */
367   public void tqli() throws Exception
368   {
369     int n = rows;
370
371     int m;
372     int l;
373     int iter;
374     int i;
375     int k;
376     double s;
377     double r;
378     double p;
379     ;
380
381     double g;
382     double f;
383     double dd;
384     double c;
385     double b;
386
387     for (i = 2; i <= n; i++)
388     {
389       e[i - 2] = e[i - 1];
390     }
391
392     e[n - 1] = 0.0;
393
394     for (l = 1; l <= n; l++)
395     {
396       iter = 0;
397
398       do
399       {
400         for (m = l; m <= (n - 1); m++)
401         {
402           dd = Math.abs(d[m - 1]) + Math.abs(d[m]);
403
404           if ((Math.abs(e[m - 1]) + dd) == dd)
405           {
406             break;
407           }
408         }
409
410         if (m != l)
411         {
412           iter++;
413
414           if (iter == maxIter)
415           {
416             throw new Exception(MessageManager.formatMessage(
417                     "exception.matrix_too_many_iteration", new String[] {
418                         "tqli", Integer.valueOf(maxIter).toString() }));
419           }
420           else
421           {
422             // System.out.println("Iteration " + iter);
423           }
424
425           g = (d[l] - d[l - 1]) / (2.0 * e[l - 1]);
426           r = Math.sqrt((g * g) + 1.0);
427           g = d[m - 1] - d[l - 1] + (e[l - 1] / (g + sign(r, g)));
428           c = 1.0;
429           s = c;
430           p = 0.0;
431
432           for (i = m - 1; i >= l; i--)
433           {
434             f = s * e[i - 1];
435             b = c * e[i - 1];
436
437             if (Math.abs(f) >= Math.abs(g))
438             {
439               c = g / f;
440               r = Math.sqrt((c * c) + 1.0);
441               e[i] = f * r;
442               s = 1.0 / r;
443               c *= s;
444             }
445             else
446             {
447               s = f / g;
448               r = Math.sqrt((s * s) + 1.0);
449               e[i] = g * r;
450               c = 1.0 / r;
451               s *= c;
452             }
453
454             g = d[i] - p;
455             r = ((d[i - 1] - g) * s) + (2.0 * c * b);
456             p = s * r;
457             d[i] = g + p;
458             g = (c * r) - b;
459
460             for (k = 1; k <= n; k++)
461             {
462               f = value[k - 1][i];
463               value[k - 1][i] = (s * value[k - 1][i - 1]) + (c * f);
464               value[k - 1][i - 1] = (c * value[k - 1][i - 1]) - (s * f);
465             }
466           }
467
468           d[l - 1] = d[l - 1] - p;
469           e[l - 1] = g;
470           e[m - 1] = 0.0;
471         }
472       } while (m != l);
473     }
474   }
475
476   /**
477    * DOCUMENT ME!
478    */
479   public void tred2()
480   {
481     int n = rows;
482     int l;
483     int k;
484     int j;
485     int i;
486
487     double scale;
488     double hh;
489     double h;
490     double g;
491     double f;
492
493     this.d = new double[rows];
494     this.e = new double[rows];
495
496     for (i = n - 1; i >= 1; i--)
497     {
498       l = i - 1;
499       h = 0.0;
500       scale = 0.0;
501
502       if (l > 0)
503       {
504         for (k = 0; k < l; k++)
505         {
506           scale += Math.abs(value[i][k]);
507         }
508
509         if (scale == 0.0)
510         {
511           e[i] = value[i][l];
512         }
513         else
514         {
515           for (k = 0; k < l; k++)
516           {
517             value[i][k] /= scale;
518             h += (value[i][k] * value[i][k]);
519           }
520
521           f = value[i][l];
522
523           if (f > 0)
524           {
525             g = -1.0 * Math.sqrt(h);
526           }
527           else
528           {
529             g = Math.sqrt(h);
530           }
531
532           e[i] = scale * g;
533           h -= (f * g);
534           value[i][l] = f - g;
535           f = 0.0;
536
537           for (j = 0; j < l; j++)
538           {
539             value[j][i] = value[i][j] / h;
540             g = 0.0;
541
542             for (k = 0; k < j; k++)
543             {
544               g += (value[j][k] * value[i][k]);
545             }
546
547             for (k = j; k < l; k++)
548             {
549               g += (value[k][j] * value[i][k]);
550             }
551
552             e[j] = g / h;
553             f += (e[j] * value[i][j]);
554           }
555
556           hh = f / (h + h);
557
558           for (j = 0; j < l; j++)
559           {
560             f = value[i][j];
561             g = e[j] - (hh * f);
562             e[j] = g;
563
564             for (k = 0; k < j; k++)
565             {
566               value[j][k] -= ((f * e[k]) + (g * value[i][k]));
567             }
568           }
569         }
570       }
571       else
572       {
573         e[i] = value[i][l];
574       }
575
576       d[i] = h;
577     }
578
579     d[0] = 0.0;
580     e[0] = 0.0;
581
582     for (i = 0; i < n; i++)
583     {
584       l = i - 1;
585
586       if (d[i] != 0.0)
587       {
588         for (j = 0; j < l; j++)
589         {
590           g = 0.0;
591
592           for (k = 0; k < l; k++)
593           {
594             g += (value[i][k] * value[k][j]);
595           }
596
597           for (k = 0; k < l; k++)
598           {
599             value[k][j] -= (g * value[k][i]);
600           }
601         }
602       }
603
604       d[i] = value[i][i];
605       value[i][i] = 1.0;
606
607       for (j = 0; j < l; j++)
608       {
609         value[j][i] = 0.0;
610         value[i][j] = 0.0;
611       }
612     }
613   }
614
615   /**
616    * DOCUMENT ME!
617    */
618   public void tqli2() throws Exception
619   {
620     int n = rows;
621
622     int m;
623     int l;
624     int iter;
625     int i;
626     int k;
627     double s;
628     double r;
629     double p;
630     ;
631
632     double g;
633     double f;
634     double dd;
635     double c;
636     double b;
637
638     for (i = 2; i <= n; i++)
639     {
640       e[i - 2] = e[i - 1];
641     }
642
643     e[n - 1] = 0.0;
644
645     for (l = 1; l <= n; l++)
646     {
647       iter = 0;
648
649       do
650       {
651         for (m = l; m <= (n - 1); m++)
652         {
653           dd = Math.abs(d[m - 1]) + Math.abs(d[m]);
654
655           if ((Math.abs(e[m - 1]) + dd) == dd)
656           {
657             break;
658           }
659         }
660
661         if (m != l)
662         {
663           iter++;
664
665           if (iter == maxIter)
666           {
667             throw new Exception(MessageManager.formatMessage(
668                     "exception.matrix_too_many_iteration", new String[] {
669                         "tqli2", Integer.valueOf(maxIter).toString() }));
670           }
671           else
672           {
673             // System.out.println("Iteration " + iter);
674           }
675
676           g = (d[l] - d[l - 1]) / (2.0 * e[l - 1]);
677           r = Math.sqrt((g * g) + 1.0);
678           g = d[m - 1] - d[l - 1] + (e[l - 1] / (g + sign(r, g)));
679           c = 1.0;
680           s = c;
681           p = 0.0;
682
683           for (i = m - 1; i >= l; i--)
684           {
685             f = s * e[i - 1];
686             b = c * e[i - 1];
687
688             if (Math.abs(f) >= Math.abs(g))
689             {
690               c = g / f;
691               r = Math.sqrt((c * c) + 1.0);
692               e[i] = f * r;
693               s = 1.0 / r;
694               c *= s;
695             }
696             else
697             {
698               s = f / g;
699               r = Math.sqrt((s * s) + 1.0);
700               e[i] = g * r;
701               c = 1.0 / r;
702               s *= c;
703             }
704
705             g = d[i] - p;
706             r = ((d[i - 1] - g) * s) + (2.0 * c * b);
707             p = s * r;
708             d[i] = g + p;
709             g = (c * r) - b;
710
711             for (k = 1; k <= n; k++)
712             {
713               f = value[k - 1][i];
714               value[k - 1][i] = (s * value[k - 1][i - 1]) + (c * f);
715               value[k - 1][i - 1] = (c * value[k - 1][i - 1]) - (s * f);
716             }
717           }
718
719           d[l - 1] = d[l - 1] - p;
720           e[l - 1] = g;
721           e[m - 1] = 0.0;
722         }
723       } while (m != l);
724     }
725   }
726
727   /**
728    * DOCUMENT ME!
729    * 
730    * @param a
731    *          DOCUMENT ME!
732    * @param b
733    *          DOCUMENT ME!
734    * 
735    * @return DOCUMENT ME!
736    */
737   public double sign(double a, double b)
738   {
739     if (b < 0)
740     {
741       return -Math.abs(a);
742     }
743     else
744     {
745       return Math.abs(a);
746     }
747   }
748
749   /**
750    * Returns an array containing the values in the specified column
751    * 
752    * @param col
753    * 
754    * @return
755    */
756   public double[] getColumn(int col)
757   {
758     double[] out = new double[rows];
759
760     for (int i = 0; i < rows; i++)
761     {
762       out[i] = value[i][col];
763     }
764
765     return out;
766   }
767
768   /**
769    * DOCUMENT ME!
770    * 
771    * @param ps
772    *          DOCUMENT ME!
773    */
774   public void printD(PrintStream ps)
775   {
776     for (int j = 0; j < rows; j++)
777     {
778       Format.print(ps, "%15.4e", d[j]);
779     }
780   }
781
782   /**
783    * DOCUMENT ME!
784    * 
785    * @param ps
786    *          DOCUMENT ME!
787    */
788   public void printE(PrintStream ps)
789   {
790     for (int j = 0; j < rows; j++)
791     {
792       Format.print(ps, "%15.4e", e[j]);
793     }
794   }
795 }