la4j - Linear Algebra for Java

/*
 * Copyright 2011, Vladimir Kostyukov
 * 
 * This file is part of la4j project (http://la4j.googlecode.com)
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * You may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 * 
 *      http://www.apache.org/licenses/LICENSE-2.0
 *      
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package la4j.matrix;

import java.io.Externalizable;

import la4j.decomposition.MatrixDecompositor;
import la4j.err.MatrixDecompositionException;
import la4j.err.MatrixException;
import la4j.err.MatrixInversionException;
import la4j.factory.Factory;
import la4j.inversion.MatrixInvertor;
import la4j.io.IOConstants;
import la4j.vector.Vector;

public interface Matrix extends Externalizable, Cloneable, IOConstants {

	public static final double EPS = 10e-7;
	
	/**
	 * Get (i, j) element of matrix;
	 *  
	 * @param i the row of matrix
	 * @param j the column of matrix
	 * @return element at (i, j) in matrix
	 */
	public double get(int i, int j);
	
	/**
	 * Set (i, j) element of matrix;
	 * 
	 * @param i the row of matrix
	 * @param j the column of matrix
	 * @param value value to be stored at (i, j) in matrix
	 */
	public void set(int i, int j, double value);

	/**
	 * Resize matrix;
	 *  
	 * @param rows the rows number
	 * @param columns the columns number
	 */
	public void resize(int rows, int columns);
	
	/**
	 * Convert matrix to double array;
	 *  
	 * @return array with matrix data
	 */
	public double[][] toArray();
	
	/**
	 * Convert matrix to double array with deep copy;
	 *  
	 * @return array with matrix data
	 */
	public double[][] toArrayCopy();

	/**
	 * Swap i and j rows of matrix;
	 * 
	 * @param i the i row
	 * @param j the j row
	 */
	public void swapRows(int i, int j);
	
	/**
	 * Swap i and i columns of matrix;
	 * 
	 * @param i column
	 * @param j column
	 */
	public void swapColumns(int i, int j);

	/**
	 * Get rows number of matrix;
	 * 
	 * @return rows number
	 */
	public int rows();
	
	/**
	 * Get columns number of matrix;
	 * 
	 * @return columns number
	 */
	public int columns();
	
	/**
	 * Get number of non-zero elements of matrix;
	 *  
	 * @return non-zero elements
	 */
	public int nonzero();
	
	/**
	 * Transpose the matrix;
	 * 
	 * @return transposed matrix
	 */
	public Matrix transpose();
	
	/**
	 * Transpose the matrix with specified factory; 
	 *  
	 * @param factory
	 * @return
	 */
	public Matrix transpose(Factory factory);
	
	/**
	 * Scale matrix;
	 * 
	 * @param value matrix to be scaled
	 * @return scaled matrix
	 */
	public Matrix multiply(double value);

	/**
	 * Multiply matrix to value with factory;
	 * 
	 * @param value
	 * @param factory
	 * @return
	 */
	public Matrix multiply(double value, Factory factory);
	
	/**
	 * Multiply matrix by vector;
	 * 
	 * @param vector to be multiplied
	 * @return multiplied matrix
	 * @throws MatrixException
	 */
	public Vector multiply(Vector vector) throws MatrixException;
	
	/**
	 * Multiply matrix by vector with specified factory;
	 * 
	 * @param vector to be multiplied
	 * @param factory
	 * @return multiplied matrix
	 * @throws MatrixException
	 */
	public Vector multiply(Vector vector, Factory factory) throws MatrixException;
	
	/**
	 * Multiply matrix by matrix;
	 * 
	 * @param matrix to be multiplied
	 * @return multiplied matrix
	 * @throws MatrixException
	 */
	public Matrix multiply(Matrix matrix) throws MatrixException;
	
	/**
	 * Multiply matrix to matrix with specified factory;
	 * 
	 * @param matrix
	 * @param factory
	 * @return
	 * @throws MatrixException
	 */
	public Matrix multiply(Matrix matrix, Factory factory) throws MatrixException;
	
	/**
	 * Subtract value from matrix;
	 * 
	 * @param value to be subtracted
	 * @return subtracted matrix
	 */
	public Matrix subtract(double value);
	
	/**
	 * Subtract value from matrix with specified factory;
	 * 
	 * @param value
	 * @param factory
	 * @return
	 */
	public Matrix subtract(double value, Factory factory);
	
	/**
	 * Subtract matrix by matrix;
	 * 
	 * @param matrix to be subtracted
	 * @return subtracted matrix
	 * @throws MatrixException
	 */
	public Matrix subtract(Matrix matrix) throws MatrixException;
	
	/**
	 * Subtract matrix from matrix with specified factory;
	 *  
	 * @param matrix
	 * @param factory
	 * @return
	 * @throws MatrixException
	 */
	public Matrix subtract(Matrix matrix, Factory factory) throws MatrixException; 
	
	/**
	 * Add value to matrix;
	 * 
	 * @param value to be added
	 * @return added matrix
	 */
	public Matrix add(double value);
	
	/**
	 * Add value to matrix with specified factory;
	 * 
	 * @param value
	 * @param factory
	 * @return
	 */
	public Matrix add(double value, Factory factory);
	
	/**
	 * Add matrix by matrix;
	 * 
	 * @param matrix to be added
	 * @return added matrix
	 * @throws MatrixException
	 */
	public Matrix add(Matrix matrix) throws MatrixException;
	
	/**
	 * Add matrix to matrix with specified factory;
	 * 
	 * @param matrix
	 * @param factory
	 * @return
	 * @throws MatrixException
	 */
	public Matrix add(Matrix matrix, Factory factory) throws MatrixException;
	
	/**
	 * Dived matrix to value;
	 *  
	 * @param value
	 * @return 
	 */
	public Matrix div(double value);
	
	/**
	 * Dived matrix to value with specified factory;
	 * 
	 * @param value
	 * @param factory
	 * @return
	 */
	public Matrix div(double value, Factory factory);
	
	/**
	 * Calculate the trace of matrix; 
	 * 
	 * @return trace of matrix
	 */
	public double trace();
	
	/**
	 * Calculate determinant of matrix;
	 *  
	 * @return determinant;
	 */
	public double determinant();

	/**
	 * Get the i-th row of matrix;
	 * 
	 * @param i row
	 * @return the i-th row
	 */
	public Vector getRow(int i);
	
	/**
	 * Get the i-th column of matrix;
	 * 
	 * @param i column
	 * @return the i-th column
	 */
	public Vector getColumn(int i);

	/**
	 * Set the i-th row of matrix;
	 * 
	 * @param i row
	 * @param row
	 */
	public void setRow(int i, Vector row);
	
	/**
	 * Set the i-th column of matrix;
	 * 
	 * @param i column
	 * @param column 
	 */
	public void setColumn(int i, Vector column);
	
	/**
	 * Check the matrix symmetries; 
	 * 
	 * @return 
	 */
	public boolean isSymmetric();

	/**
	 * Check the matrix triangles;
	 * 
	 * @return
	 */
	public boolean isTriangle();
	
	/**
	 * Convert matrix to triangle;
	 * 
	 * @return 
	 */
	public Matrix triangularize();
	
	/**
	 * Convert matrix to triangle with factory;
	 * 
	 * @param factory
	 * @return
	 */
	public Matrix triangularize(Factory factory);
	
	/**
	 * Decompose matrix;
	 * 	
	 * @param decompositor
	 * @return
	 * @throws MatrixDecompositionException
	 */
	public Matrix[] decompose(MatrixDecompositor decompositor) throws MatrixDecompositionException;

	/**
	 * Decompose matrix;
	 * 
	 * @param decompositor
	 * @param factory
	 * @return
	 * @throws MatrixDecompositionException
	 */
	public Matrix[] decompose(MatrixDecompositor decompositor, Factory factory) throws MatrixDecompositionException;
	
	/**
	 * Invert matrix;
	 *  
	 * @param invertor
	 * @return
	 * @throws MatrixInversionException
	 */
	public Matrix inverse(MatrixInvertor invertor) throws MatrixInversionException;
	
	/**
	 * Invert matrix;
	 *  
	 * @param invertor
	 * @param factory
	 * @return
	 * @throws MatrixInversionException
	 */
	public Matrix inverse(MatrixInvertor invertor, Factory factory) throws MatrixInversionException;
	
	/**
	 * Get blank matrix;
	 * 
	 * @return blanked matrix
	 */
	public Matrix blank();
	
	/**
	 * Get blank matrix with factory;
	 *  
	 * @param factory
	 * @return
	 */
	public Matrix blank(Factory factory);
		
	/**
	 * Get copy of matrix;
	 * 
	 * @return
	 */
	public Matrix copy();
	
	/**
	 * Get copy of matrix with factory;
	 * 
	 * @param factory
	 * @return
	 */
	public Matrix copy(Factory factory);
	
	/**
	 * Convert matrix to string;
	 * 
	 * @return converted matrix
	 */
	public String toString();
	
	/**
	 *  
	 * @return
	 */
	public Matrix clone();
}