path: root/mtxmatrix.h

/* $Id$ */

/*
 * Copyright (C) 2006 Richard Braun
 * 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 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 General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

#ifndef _MTXMATRIX_H
#define _MTXMATRIX_H

#include <string>
#include <iostream>

#include "mtxvalue.h"
#include "mtxrational.h"

/**
 * A matrix.
 * 
 * This class allows to create matrices which consist of an array of
 * MtxRational objects, the number of rows, the number of columns, and
 * the length of the array which is rows * columns.
 */
class MtxMatrix: public MtxValue
{
  private:
    /**
     * Array of rationals.
     */
    MtxRational *rationals;

    /**
     * The length of the array of rationals.
     * 
     * It is maintained internally to avoid computing rows * columns.
     * 
     * @see getLength()
     */
    size_t length;

    /**
     * Number of rows.
     * 
     * @see getRows()
     */
    size_t rows;

    /**
     * Number of columns.
     * 
     * @see getColumns()
     */
    size_t columns;

    /**
     * Throw an MtxException exception if the rows of the current matrix and
     * the rows of the given matrix differ.
     * 
     * This check if performed mainly before augmenting matrices.
     * 
     * @see checkDimensions()
     */
    void checkRows(const MtxMatrix &matrix) const;

    /**
     * Check that both dimensions of the current matrix and the given matrix
     * match.
     * 
     * A MtxException exception is thrown if one of the dimensions differ.
     * Mainly used for addition like operations.
     * 
     * @see checkRows()
     */
    void checkDimensions(const MtxMatrix &matrix) const;

    /**
     * Check compatibility of the current matrix with the given matrix.
     * 
     * Two matrices are compatible if the number of columns of the first
     * is equal to the number of rows of the second. If matrices are not
     * compatible, an MtxException exception is raised. Mainly used for
     * matrix multiplication.
     */
    void checkCompatibility(const MtxMatrix &matrix) const;

    /**
     * Check that the current matrix is a square matrix.
     * 
     * Throw an MtxException exception if the number of rows differs from
     * the number of columns. Mainly used for LU decomposition.
     */
    void checkSquare() const;

    /**
     * Add two rows.
     * 
     * @param dst_row the index of the row which is updated
     * @param src_row the index of the row which is added to dst_row
     * @param rational a coefficient which is applied to each element of
     *                 src_row before addition
     */
    void addRows(size_t dst_row, size_t src_row, const MtxRational &rational);

    /**
     * Subtract two rows.
     * 
     * @param dst_row the index of the row which is updated
     * @param src_row the index of the row which is subtracted from dst_row
     * @param rational a coefficient which is applied to each element of
     *                 src_row before subtraction
     */
    void subtractRows(size_t dst_row, size_t src_row,
                      const MtxRational &rational);

    /**
     * Multiply a row by a rational.
     * 
     * @param row the index of the row which is updated
     * @param rational a coefficient which is applied to each element of
     *                 row
     */
    void multiplyRow(size_t row, const MtxRational &rational);

    /**
     * Divide a row by a rational.
     * 
     * @param row the index of the row which is updated
     * @param rational a coefficient which inverse is applied to each element
     *                 of row
     */
    void divideRow(size_t row, const MtxRational &rational);

    /**
     * Switch two rows.
     * 
     * @param r1 the index of the first row
     * @param r2 the index of the second row
     */
    void switchRows(size_t r1, size_t r2);

    /**
     * Inverse the current matrix if this matrix is a unit lower triangular
     * matrix.
     * 
     * Used for inversion of matrices.
     */
    MtxMatrix l_inverted() const;

    /**
     * Inverse the current matrix if this matrix is an upper triangular matrix.
     * 
     * Used for inversion of matrices.
     */
    MtxMatrix u_inverted() const;

  public:
    /**
     * Default constructor.
     */
    MtxMatrix();

    /**
     * Create a matrix from an array of rationals, the number of rows and the
     * number of columns. The caller must ensure coherent values are passed.
     */
    MtxMatrix(MtxRational *rationals, size_t rows, size_t columns);

    MtxMatrix(const MtxMatrix &matrix);
    virtual ~MtxMatrix();

    MtxMatrix & operator=(const MtxMatrix &matrix);

    /*
     * Some operators are available for easiness.
     */

    /**
     * Return the address of the line at requested index.
     * 
     * NULL is returned if index is invalid. Usage example :
     * MtxRational r;
     * r = matrix[1][2];
     */
    MtxRational * operator[](size_t index) const;
    MtxMatrix operator+() const;
    MtxMatrix operator-() const;
    bool operator==(const MtxMatrix &matrix) const;
    bool operator!=(const MtxMatrix &matrix) const;
    MtxMatrix operator+(const MtxMatrix &matrix) const;
    MtxMatrix operator+(const MtxRational &rational) const;
    MtxMatrix & operator+=(const MtxMatrix &matrix);
    MtxMatrix operator-(const MtxMatrix &matrix) const;
    MtxMatrix operator-(const MtxRational &rational) const;
    MtxMatrix & operator-=(const MtxMatrix &matrix);
    MtxMatrix operator*(const MtxMatrix &matrix) const;
    MtxMatrix & operator*=(const MtxMatrix &matrix);
    MtxMatrix operator*(const MtxRational &rational) const;
    MtxMatrix & operator*=(const MtxRational &rational);
    MtxMatrix operator/(const MtxMatrix &matrix) const;
    MtxMatrix operator/(const MtxRational &rational) const;

    friend std::ostream & operator<<(std::ostream &cout,
                                     const MtxMatrix &matrix);

    /**
     * Return length.
     * 
     * @see length
     */
    size_t getLength() const;

    /**
     * Return number of rows.
     * 
     * @see rows
     */
    size_t getRows() const;

    /**
     * Return number of columns.
     * 
     * @see columns
     */
    size_t getColumns() const;

    /**
     * Normalize each rational of the matrix.
     */
    MtxMatrix & normalize();

    /**
     * Return the transpose of the matrix.
     */
    MtxMatrix transpose() const;

    /**
     * Return the current matrix augmented with the given matrix.
     */
    MtxMatrix augmented(const MtxMatrix &matrix) const;

    /**
     * Apply an LU decomposition.
     * 
     * @param L set to the unit lower triangular matrix
     * @param U set to the upper triangular matrix
     */
    void luDecomposition(MtxMatrix &L, MtxMatrix &U) const;

    /**
     * Return the determinant.
     */
    MtxRational determinant() const;

    /**
     * Return the inverted matrix.
     */
    MtxMatrix inverted() const;

    /**
     * Return a string representation of the matrix.
     * 
     * If float_string is true, matrix elements are returned in floating
     * point representation, otherwise, they are returned in fractional
     * representation.
     * 
     * @param float_string control rendering of the matrix elements
     * @see toString()
     * @see toFloatString()
     */
    std::string toString(bool float_string) const;

    /**
     * Return a string representation of the matrix.
     * 
     * Similar to toString(false).
     * 
     * @see toString(bool float_string) const
     * @see toFloatString()
     */
    virtual std::string toString() const;

    /**
     * Return a string representation of the matrix.
     * 
     * Similar to toString(true).
     * 
     * @see toString(bool float_string) const
     * @see toString()
     */
    std::string toFloatString() const;

    /*
     * See mtxvalue.h.
     */
    MTXVALUE_CLONE_METHOD_DECLARATION(MtxMatrix);
    virtual MtxValue * add(const MtxValue *value) const;
    virtual MtxValue * subtract(const MtxValue *value) const;
    virtual MtxValue * multiply(const MtxValue *value) const;
    virtual MtxValue * divide(const MtxValue *value) const;
    virtual MtxValue * opposite() const;

    /**
     * Return a zero matrix.
     * 
     * @param rows number of rows of the zero matrix
     * @param columns number of columns of the zero matrix
     */
    static MtxMatrix getZeroMatrix(size_t rows, size_t columns);

    /**
     * Return an identity matrix.
     * 
     * Note that an identity matrix is a square matrix.
     * 
     * @param n dimension of identity matrix
     */
    static MtxMatrix getIdentityMatrix(size_t n);
};

#endif /* _MTXMATRIX_H */