gimatrix.java

化学图形处理软件

/*  $RCSfile$
 *  $Author: egonw $
 *  $Date: 2007-01-04 18:46:10 +0100 (Thu, 04 Jan 2007) $
 *  $Revision: 7636 $
 *
 *  Copyright (C) 1997-2007  The Chemistry Development Kit (CDK) project
 *
 *  Contact: [e-mail]
 *
 *  This program is free software; you can redistribute it and/or
 *  modify it under the terms of the GNU Lesser General Public License
 *  as published by the Free Software Foundation; either version 2.1
 *  of the License, or (at your option) any later version.
 *
 *  This program is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU Lesser General Public License for more details.
 *
 *  You should have received a copy of the GNU Lesser General Public License
 *  along with this program; if not, write to the Free Software
 *  Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 */
package org.openscience.cdk.graph.invariant;

import org.openscience.cdk.graph.invariant.exception.BadMatrixFormatException;
import org.openscience.cdk.graph.invariant.exception.IndexOutOfBoundsException;
import org.openscience.cdk.graph.invariant.exception.MatrixNotInvertibleException;

/**
 * This class is intended to provide the user an efficient way of implementing matrix of double number and
 * using normal operations (linear operations, addition, substraction, multiplication, inversion, concatenation)
 * on them. The internal representation of a matrix is an array of array of double objects. For the moment,
 * double class is the best way I have developped to perform exact operation on numbers; however, for
 * irdoubles, normal operations on float and doubles have to be performed, with the well-known risks of error
 * this implies. This class also provides a way of representing matrix as arrays of String for output use.
 *
 * <P>Please note that although in most books matrix elements' indexes take values between [1..n] I chose not
 * to disturb Java language way of calling indexes; so the indexes used here take values between [0..n-1] instead.
 *
 * @author Jean-Sebastien Senecal
 * @version 1.0
 * @cdk.created 1999-05-20
 */
public class GIMatrix {

    private double[][] array; // the matrix itself as an array of doubles
    private int m, n; // matrix's params (m=no of line, n=no of columns)
    
    /**
     * Class constructor. Uses an array of integers to create a new Matrix object. Note that integers
     * will be converted to double objects so mathematical operations may be properly performed and
     * provide exact solutions. The given array should be properly instantiated as a matrix i.e. it
     * must contain a fixed number of lines and columns, otherwise an exception will be thrown.
     * Array must be at leat 1x1.
     * @param array an array of integer (first index is the line, second is the column)
     * @exception BadMatrixFormatException in case the given array is unproper to construct a matrix
     */
    public GIMatrix(int[][] array)  {
	double[][] temp = new double[array.length][];
	for (int i = 0; i < array.length; i++) {
	    temp[i] = new double[array[i].length]; // line by line ...
	    for (int j = 0; j < array[i].length; j++)
		temp[i][j] = array[i][j]; // converts ints to doubles
	}
//	verifyMatrixFormat(temp);
	this.array = temp;
	m = temp.length;
	n = temp[0].length;
    } // constructor Matrix(int[][])

    /**
     * Class constructor. Uses an array of doubles to create a new Matrix object. The given array should
     * be properly instantiated as a matrix i.e. it must contain a fixed number of lines and columns,
     * otherwise an exception will be thrown. Array must be at leat 1x1.
     *
     * @param array an array of double objects (first index is the line, second is the column)
     * @exception BadMatrixFormatException in case the given array is unproper to construct a matrix
     */
    public GIMatrix(double[][] array) throws BadMatrixFormatException {
	verifyMatrixFormat(array);
	double[][] temp = new double[array.length][];
	for (int i = 0; i < array.length; i++) {
	    temp[i] = new double[array[i].length]; // line by line ...
	    for (int j = 0; j < array[i].length; j++)
		temp[i][j] = array[i][j];
	}
	this.array = temp;
	m = array.length;
	n = array[0].length;
    } // constructor Matrix(double[][])
    
    /**
     * Class constructor. Creates a new Matrix object with fixed dimensions. The matrix is
     * initialised to the "zero" matrix.
     *
     * @param line number of lines
     * @param col number of columns
     */
    public GIMatrix(int line, int col) {
		array = new double[line][col];
		for (int i = 0; i < line; i++)
			for (int j = 0; j < col; j++)
				array[i][j] = 0.0;
		m = line;
		n = col;		
    } // constructor Matrix(int,int)

    /**
     * Class constructor. Copies an already existing Matrix object in a new Matrix object.
     * @param matrix a Matrix object
     */
    public GIMatrix(GIMatrix matrix) {
	double[][] temp = new double[matrix.height()][];
	for (int i = 0; i < matrix.height(); i++) {
	    temp[i] = new double[matrix.width()]; // line by line ...
	    for (int j = 0; j < matrix.width(); j++) {
		try { temp[i][j] = matrix.getValueAt(i,j); }
		catch (IndexOutOfBoundsException e) {} // never happens
	    }
	}
	this.array = temp;
	m = array.length;
	n = array[0].length;
    } // constructor Matrix(Matrix)

    /**
     * Class constructor. Creates a new Matrix object using a table of matrices (an array of Matrix objects).
     * The given array should be properly instantiated i.e. it must contain a fixed number of lines and columns, 
     * otherwise an exception will be thrown.
     * @param table an array of matrices
     * @exception BadMatrixFormatException if the table is not properly instantiated
     */
    public GIMatrix(GIMatrix[][] table) throws BadMatrixFormatException {
	verifyTableFormat(table);
	m = n = 0;
	for (int i = 0; i < table.length; i++) m += table[i][0].height();
	for (int j = 0; j < table[0].length; j++) n += table[0][j].width();
	double[][] temp = new double[m][n];
	int k = 0; // counters for matrices
	for (int i = 0; i < m; i++) {
	    temp[i] = new double[n]; // line by line ...
	    if (i == table[k][0].height()) k++; // last line of matrix reached
	    int h = 0;
	    for (int j = 0; j < n; j++) {
		if (j == table[k][h].width()) h++; // last column of matrix reached
		try {
		    GIMatrix tempMatrix = table[k][h];
		    temp[i][j] = tempMatrix.getValueAt(i - k*tempMatrix.height(),j - h*tempMatrix.width());
		}
		catch (IndexOutOfBoundsException e) {} // never happens
	    }
	}
	this.array = temp;
    } // constructor Matrix(Matrix)
    
    /**
     * Returns the number of lines of the matrix.
     * @return the height of the matrix
     */
    public int height() { return m; } // method heigth()

    /**
     * Returns the number of columns of the matrix.
     * @return the width of the matrix
     */
    public int width() { return n; } // method width()

    /**
     * Returns the internal representation of the matrix, that is an array of double objects.
     * @return an array of double equivalent to the matrix
     */
    public double[][] getArrayValue() { return array; } // method getArrayValue()
    
    /**
     * Resets the value of the matrix to the given array of double numbers
     * @param array an array of double objects (first index is the line, second is the column)
     * @exception BadMatrixFormatException in case the given array is unproper to construct a matrix
     */
    public void setArrayValue(double[][] array) throws BadMatrixFormatException {
	verifyMatrixFormat(array);
	this.array = array;
    } // method setArrayValue(double[][])

    /**
     * Returns the value of the given element.
     * @param i the line number
     * @param j the column number
     * @return the double at the given index in the Matrix
     * @exception IndexOutOfBoundsException if the given index is out of the matrix's range
     */
    public double getValueAt(int i, int j) throws IndexOutOfBoundsException { 
	if ( (i < 0)||(i >= m)||(j < 0)||(j >= n) ) throw new IndexOutOfBoundsException();
	return array[i][j];
    } // method getValueAt(int,int)
    
    /**
     * Sets the value of the element at the given index.
     * @param i the line number
     * @param j the column number
     * @param element the double to place at the given index in the Matrix
     * @exception IndexOutOfBoundsException if the given index is out of the matrix's range
     */
    public void setValueAt(int i, int j, double element) throws IndexOutOfBoundsException {
	if ( (i < 0)||(i >= m)||(j < 0)||(j >= n) ) throw new IndexOutOfBoundsException();
	array[i][j] = element;
    } // method setValueAt(int,int,double)

    /**
     * Returns the line-matrix at the given line index
     * @param i the line number
     * @return the specified line as a Matrix object
     * @exception IndexOutOfBoundsException if the given index is out of the matrix's range
     */ 
    public GIMatrix getLine(int i) throws IndexOutOfBoundsException {
	if ( (i < 0)||(i >= m) ) throw new IndexOutOfBoundsException();
	double[][] line = new double[1][n];
	for (int k = 0; k < n; k++) line[0][k] = array[i][k];
	try { return new GIMatrix(line); } // format is always OK anyway ...
	catch (BadMatrixFormatException e) { return null; }
    } // method getLine(int)

    /**
     * Returns the column-matrix at the given line index
     * @param j the column number
     * @return the specified column as a Matrix object
     * @exception IndexOutOfBoundsException if the given index is out of the matrix's range
     */ 
    public GIMatrix getColumn(int j) throws IndexOutOfBoundsException {
	if ( (j < 0)||(j >= n) ) throw new IndexOutOfBoundsException();
	double[][] column = new double[m][1];
	for (int k = 0; k < m; k++) column[k][0] = array[k][j];
	try { return new GIMatrix(column); } // format is always OK anyway ...
	catch (BadMatrixFormatException e) { return null; }
    } // method getColumn(int)

    /**
     * Sets the line of the matrix at the specified index to a new value.
     * @param i the line number
     * @param line the line to be placed at the specified index
     * @exception IndexOutOfBoundsException if the given index is out of the matrix's range
     * @exception BadMatrixFormatException in case the given Matrix is unproper to replace a line of this Matrix
     */