GiNaC  1.6.2
Public Member Functions | Protected Member Functions | Protected Attributes
GiNaC::matrix Class Reference

Symbolic matrices. More...

#include <matrix.h>

Inheritance diagram for GiNaC::matrix:
GiNaC::basic GiNaC::refcounted

List of all members.

Public Member Functions

 matrix (unsigned r, unsigned c)
 Very common ctor.
 matrix (unsigned r, unsigned c, const exvector &m2)
 Ctor from representation, for internal use only.
 matrix (unsigned r, unsigned c, const lst &l)
 Construct matrix from (flat) list of elements.
matrix_init< ex,
exvector::iterator > 
operator= (const ex &x)
size_t nops () const
 nops is defined to be rows x columns.
ex op (size_t i) const
 returns matrix entry at position (i/col, icol).
exlet_op (size_t i)
 returns writable matrix entry at position (i/col, icol).
ex eval (int level=0) const
 Evaluate matrix entry by entry.
ex evalm () const
 Evaluate sums, products and integer powers of matrices.
ex subs (const exmap &m, unsigned options=0) const
 Substitute a set of objects by arbitrary expressions.
ex eval_indexed (const basic &i) const
 Automatic symbolic evaluation of an indexed matrix.
ex add_indexed (const ex &self, const ex &other) const
 Sum of two indexed matrices.
ex scalar_mul_indexed (const ex &self, const numeric &other) const
 Product of an indexed matrix with a number.
bool contract_with (exvector::iterator self, exvector::iterator other, exvector &v) const
 Contraction of an indexed matrix with something else.
ex conjugate () const
 Complex conjugate every matrix entry.
ex real_part () const
ex imag_part () const
void archive (archive_node &n) const
 Save (a.k.a.
void read_archive (const archive_node &n, lst &syms)
 Read (a.k.a.
unsigned rows () const
 Get number of rows.
unsigned cols () const
 Get number of columns.
matrix add (const matrix &other) const
 Sum of matrices.
matrix sub (const matrix &other) const
 Difference of matrices.
matrix mul (const matrix &other) const
 Product of matrices.
matrix mul (const numeric &other) const
 Product of matrix and scalar.
matrix mul_scalar (const ex &other) const
 Product of matrix and scalar expression.
matrix pow (const ex &expn) const
 Power of a matrix.
const exoperator() (unsigned ro, unsigned co) const
 operator() to access elements for reading.
exoperator() (unsigned ro, unsigned co)
 operator() to access elements for writing.
matrixset (unsigned ro, unsigned co, const ex &value)
matrix transpose () const
 Transposed of an m x n matrix, producing a new n x m matrix object that represents the transposed.
ex determinant (unsigned algo=determinant_algo::automatic) const
 Determinant of square matrix.
ex trace () const
 Trace of a matrix.
ex charpoly (const ex &lambda) const
 Characteristic Polynomial.
matrix inverse () const
 Inverse of this matrix.
matrix solve (const matrix &vars, const matrix &rhs, unsigned algo=solve_algo::automatic) const
 Solve a linear system consisting of a m x n matrix and a m x p right hand side by applying an elimination scheme to the augmented matrix.
unsigned rank () const
 Compute the rank of this matrix.
bool is_zero_matrix () const
 Function to check that all elements of the matrix are zero.

Protected Member Functions

bool match_same_type (const basic &other) const
 Returns true if the attributes of two objects are similar enough for a match.
unsigned return_type () const
ex determinant_minor () const
 Recursive determinant for small matrices having at least one symbolic entry.
int gauss_elimination (const bool det=false)
 Perform the steps of an ordinary Gaussian elimination to bring the m x n matrix into an upper echelon form.
int division_free_elimination (const bool det=false)
 Perform the steps of division free elimination to bring the m x n matrix into an upper echelon form.
int fraction_free_elimination (const bool det=false)
 Perform the steps of Bareiss' one-step fraction free elimination to bring the matrix into an upper echelon form.
int pivot (unsigned ro, unsigned co, bool symbolic=true)
 Partial pivoting method for matrix elimination schemes.
void print_elements (const print_context &c, const char *row_start, const char *row_end, const char *row_sep, const char *col_sep) const
void do_print (const print_context &c, unsigned level) const
 Default output to stream.
void do_print_latex (const print_latex &c, unsigned level) const
void do_print_python_repr (const print_python_repr &c, unsigned level) const
 Python parsable output to stream.

Protected Attributes

unsigned row
 number of rows
unsigned col
 number of columns
exvector m
 representation (cols indexed first)

Detailed Description

Symbolic matrices.

Definition at line 94 of file matrix.h.


Constructor & Destructor Documentation

GiNaC::matrix::matrix ( unsigned  r,
unsigned  c 
)

Very common ctor.

Initializes to r x c-dimensional zero-matrix.

Parameters:
rnumber of rows
cnumber of cols

Definition at line 71 of file matrix.cpp.

References GiNaC::status_flags::not_shareable, and GiNaC::basic::setflag().

Referenced by add(), conjugate(), determinant(), eval(), imag_part(), mul(), mul_scalar(), real_part(), sub(), subs(), and transpose().

GiNaC::matrix::matrix ( unsigned  r,
unsigned  c,
const exvector m2 
)

Ctor from representation, for internal use only.

Definition at line 79 of file matrix.cpp.

References GiNaC::status_flags::not_shareable, and GiNaC::basic::setflag().

GiNaC::matrix::matrix ( unsigned  r,
unsigned  c,
const lst l 
)

Construct matrix from (flat) list of elements.

If the list has fewer elements than the matrix, the remaining matrix elements are set to zero. If the list has more elements than the matrix, the excessive elements are thrown away.

Definition at line 89 of file matrix.cpp.

References GiNaC::container< C >::begin(), c, GiNaC::container< C >::end(), m, GiNaC::status_flags::not_shareable, GiNaC::basic::setflag(), and x.


Member Function Documentation

matrix_init<ex, exvector::iterator> GiNaC::matrix::operator= ( const ex x) [inline]

Definition at line 106 of file matrix.h.

References m, and x.

size_t GiNaC::matrix::nops ( ) const [virtual]

nops is defined to be rows x columns.

Reimplemented from GiNaC::basic.

Definition at line 184 of file matrix.cpp.

References col, and row.

Referenced by add_indexed(), let_op(), GiNaC::nops(), op(), and scalar_mul_indexed().

ex GiNaC::matrix::op ( size_t  i) const [virtual]

returns matrix entry at position (i/col, icol).

Reimplemented from GiNaC::basic.

Definition at line 190 of file matrix.cpp.

References GINAC_ASSERT, m, and nops().

Referenced by add_indexed(), and scalar_mul_indexed().

ex & GiNaC::matrix::let_op ( size_t  i) [virtual]

returns writable matrix entry at position (i/col, icol).

Reimplemented from GiNaC::basic.

Definition at line 198 of file matrix.cpp.

References GiNaC::basic::ensure_if_modifiable(), GINAC_ASSERT, m, and nops().

ex GiNaC::matrix::eval ( int  level = 0) const [virtual]

Evaluate matrix entry by entry.

Reimplemented from GiNaC::basic.

Definition at line 207 of file matrix.cpp.

References c, col, GiNaC::status_flags::dynallocated, GiNaC::status_flags::evaluated, GiNaC::basic::flags, m, matrix(), GiNaC::max_recursion_level, r, and row.

Referenced by GiNaC::eval().

ex GiNaC::matrix::evalm ( ) const [inline, virtual]

Evaluate sums, products and integer powers of matrices.

Reimplemented from GiNaC::basic.

Definition at line 118 of file matrix.h.

ex GiNaC::matrix::subs ( const exmap m,
unsigned  options = 0 
) const [virtual]

Substitute a set of objects by arbitrary expressions.

The ex returned will already be evaluated.

Reimplemented from GiNaC::basic.

Definition at line 228 of file matrix.cpp.

References c, col, m, matrix(), r, and row.

Referenced by fraction_free_elimination().

ex GiNaC::matrix::eval_indexed ( const basic i) const [virtual]
ex GiNaC::matrix::add_indexed ( const ex self,
const ex other 
) const [virtual]

Sum of two indexed matrices.

Reimplemented from GiNaC::basic.

Definition at line 399 of file matrix.cpp.

References GINAC_ASSERT, GiNaC::ex::is_equal(), nops(), GiNaC::ex::nops(), op(), and GiNaC::ex::op().

ex GiNaC::matrix::scalar_mul_indexed ( const ex self,
const numeric other 
) const [virtual]

Product of an indexed matrix with a number.

Reimplemented from GiNaC::basic.

Definition at line 435 of file matrix.cpp.

References GINAC_ASSERT, mul(), nops(), op(), and GiNaC::ex::op().

bool GiNaC::matrix::contract_with ( exvector::iterator  self,
exvector::iterator  other,
exvector v 
) const [virtual]

Contraction of an indexed matrix with something else.

Reimplemented from GiNaC::basic.

Definition at line 450 of file matrix.cpp.

References GiNaC::_ex1, GINAC_ASSERT, GiNaC::is_dummy_pair(), mul(), and transpose().

ex GiNaC::matrix::conjugate ( ) const [virtual]

Complex conjugate every matrix entry.

Reimplemented from GiNaC::basic.

Definition at line 239 of file matrix.cpp.

References GiNaC::are_ex_trivially_equal(), col, GiNaC::ex::conjugate(), m, matrix(), row, and x.

ex GiNaC::matrix::real_part ( ) const [virtual]

Reimplemented from GiNaC::basic.

Definition at line 266 of file matrix.cpp.

References col, m, matrix(), and row.

ex GiNaC::matrix::imag_part ( ) const [virtual]

Reimplemented from GiNaC::basic.

Definition at line 275 of file matrix.cpp.

References col, m, matrix(), and row.

void GiNaC::matrix::archive ( archive_node n) const [virtual]

Save (a.k.a.

serialize) object into archive.

Reimplemented from GiNaC::basic.

Definition at line 128 of file matrix.cpp.

References GiNaC::archive_node::add_ex(), GiNaC::archive_node::add_unsigned(), col, m, and row.

void GiNaC::matrix::read_archive ( const archive_node n,
lst syms 
) [virtual]

Read (a.k.a.

deserialize) object from archive.

Reimplemented from GiNaC::basic.

Definition at line 108 of file matrix.cpp.

References col, GiNaC::archive_node::find_ex_by_loc(), GiNaC::archive_node::find_first(), GiNaC::archive_node::find_last(), GiNaC::archive_node::find_unsigned(), last, m, and row.

bool GiNaC::matrix::match_same_type ( const basic other) const [protected, virtual]

Returns true if the attributes of two objects are similar enough for a match.

This function must not match subexpressions (this is already done by basic::match()). Only attributes not accessible by op() should be compared. This is also the reason why this function doesn't take the wildcard replacement list from match() as an argument: only subexpressions are subject to wildcard matches. Also, this function only needs to be implemented for container classes because is_equal_same_type() is automatically used instead of match_same_type() if nops() == 0.

See also:
basic::match

Reimplemented from GiNaC::basic.

Definition at line 311 of file matrix.cpp.

References cols(), GINAC_ASSERT, and rows().

unsigned GiNaC::matrix::return_type ( ) const [inline, protected, virtual]

Reimplemented from GiNaC::basic.

Definition at line 134 of file matrix.h.

References GiNaC::return_types::noncommutative.

unsigned GiNaC::matrix::rows ( ) const [inline]
unsigned GiNaC::matrix::cols ( ) const [inline]
matrix GiNaC::matrix::add ( const matrix other) const

Sum of matrices.

Exceptions:
logic_error(incompatible matrices)

Definition at line 557 of file matrix.cpp.

References col, m, matrix(), and row.

Referenced by GiNaC::add::evalm().

matrix GiNaC::matrix::sub ( const matrix other) const

Difference of matrices.

Exceptions:
logic_error(incompatible matrices)

Definition at line 575 of file matrix.cpp.

References col, m, matrix(), and row.

matrix GiNaC::matrix::mul ( const matrix other) const

Product of matrices.

Exceptions:
logic_error(incompatible matrices)

Definition at line 593 of file matrix.cpp.

References c, col, cols(), GiNaC::is_zero(), m, matrix(), and rows().

Referenced by charpoly(), contract_with(), GiNaC::ncmul::evalm(), pow(), and scalar_mul_indexed().

matrix GiNaC::matrix::mul ( const numeric other) const

Product of matrix and scalar.

Definition at line 614 of file matrix.cpp.

References c, col, m, matrix(), r, and row.

matrix GiNaC::matrix::mul_scalar ( const ex other) const

Product of matrix and scalar expression.

Definition at line 627 of file matrix.cpp.

References c, col, GiNaC::return_types::commutative, m, matrix(), r, GiNaC::ex::return_type(), and row.

Referenced by GiNaC::mul::evalm().

matrix GiNaC::matrix::pow ( const ex expn) const
const ex & GiNaC::matrix::operator() ( unsigned  ro,
unsigned  co 
) const

operator() to access elements for reading.

Parameters:
rorow of element
cocolumn of element
Exceptions:
range_error(index out of range)

Definition at line 690 of file matrix.cpp.

References m.

ex & GiNaC::matrix::operator() ( unsigned  ro,
unsigned  co 
)

operator() to access elements for writing.

Parameters:
rorow of element
cocolumn of element
Exceptions:
range_error(index out of range)

Definition at line 704 of file matrix.cpp.

References GiNaC::basic::ensure_if_modifiable(), and m.

matrix& GiNaC::matrix::set ( unsigned  ro,
unsigned  co,
const ex value 
) [inline]

Definition at line 150 of file matrix.h.

References value.

matrix GiNaC::matrix::transpose ( ) const

Transposed of an m x n matrix, producing a new n x m matrix object that represents the transposed.

Definition at line 716 of file matrix.cpp.

References c, cols(), m, matrix(), r, and rows().

Referenced by contract_with(), and GiNaC::transpose().

ex GiNaC::matrix::determinant ( unsigned  algo = determinant_algo::automatic) const

Determinant of square matrix.

This routine doesn't actually calculate the determinant, it only implements some heuristics about which algorithm to run. If all the elements of the matrix are elements of an integral domain the determinant is also in that integral domain and the result is expanded only. If one or more elements are from a quotient field the determinant is usually also in that quotient field and the result is normalized before it is returned. This implies that the determinant of the symbolic 2x2 matrix [[a/(a-b),1],[b/(a-b),1]] is returned as unity. (In this respect, it behaves like MapleV and unlike Mathematica.)

Parameters:
algoallows to chose an algorithm
Returns:
the determinant as a new expression
Exceptions:
logic_error(matrix not square)
See also:
determinant_algo

Definition at line 741 of file matrix.cpp.

References GiNaC::_ex0, GiNaC::determinant_algo::automatic, GiNaC::determinant_algo::bareiss, c, col, GiNaC::info_flags::crational_polynomial, GiNaC::determinant_algo::divfree, division_free_elimination(), fraction_free_elimination(), GiNaC::determinant_algo::gauss, gauss_elimination(), GINAC_ASSERT, GiNaC::ex::info(), GiNaC::ex::is_zero(), GiNaC::is_zero(), GiNaC::determinant_algo::laplace, m, matrix(), GiNaC::ex::normal(), GiNaC::basic::normal(), GiNaC::info_flags::numeric, GiNaC::permutation_sign(), r, GiNaC::info_flags::rational_function, row, and GiNaC::ex::to_rational().

Referenced by charpoly(), GiNaC::determinant(), and GiNaC::resultant().

ex GiNaC::matrix::trace ( ) const

Trace of a matrix.

The result is normalized if it is in some quotient field and expanded only otherwise. This implies that the trace of the symbolic 2x2 matrix [[a/(a-b),x],[y,b/(b-a)]] is recognized to be unity.

Returns:
the sum of diagonal elements
Exceptions:
logic_error(matrix not square)

Definition at line 873 of file matrix.cpp.

References col, GiNaC::info_flags::crational_polynomial, GiNaC::ex::expand(), GiNaC::ex::info(), m, GiNaC::ex::normal(), r, and GiNaC::info_flags::rational_function.

Referenced by charpoly(), eval_indexed(), and GiNaC::trace().

ex GiNaC::matrix::charpoly ( const ex lambda) const

Characteristic Polynomial.

Following mathematica notation the characteristic polynomial of a matrix M is defined as the determiant of (M - lambda * 1) where 1 stands for the unit matrix of the same dimension as M. Note that some CASs define it with a sign inside the determinant which gives rise to an overall sign if the dimension is odd. This method returns the characteristic polynomial collected in powers of lambda as a new expression.

Returns:
characteristic polynomial as new expression
Exceptions:
logic_error(matrix not square)
See also:
matrix::determinant()

Definition at line 901 of file matrix.cpp.

References c, col, GiNaC::ex::collect(), determinant(), GiNaC::basic::ex, m, mul(), GiNaC::info_flags::numeric, poly, r, row, and trace().

Referenced by GiNaC::charpoly().

matrix GiNaC::matrix::inverse ( ) const

Inverse of this matrix.

Returns:
the inverted matrix
Exceptions:
logic_error(matrix not square)
runtime_error(singular matrix)

Definition at line 950 of file matrix.cpp.

References GiNaC::_ex1, c, col, r, row, and solve().

Referenced by GiNaC::inverse(), and pow().

matrix GiNaC::matrix::solve ( const matrix vars,
const matrix rhs,
unsigned  algo = solve_algo::automatic 
) const

Solve a linear system consisting of a m x n matrix and a m x p right hand side by applying an elimination scheme to the augmented matrix.

Parameters:
varsn x p matrix, all elements must be symbols
rhsm x p matrix
algoselects the solving algorithm
Returns:
n x p solution matrix
Exceptions:
logic_error(incompatible matrices)
invalid_argument(1st argument must be matrix of symbols)
runtime_error(inconsistent linear system)
See also:
solve_algo

Definition at line 995 of file matrix.cpp.

References GiNaC::solve_algo::automatic, GiNaC::solve_algo::bareiss, c, col, cols(), GiNaC::solve_algo::divfree, division_free_elimination(), fraction_free_elimination(), GiNaC::solve_algo::gauss, gauss_elimination(), GiNaC::basic::info(), m, n, GiNaC::basic::normal(), GiNaC::info_flags::numeric, r, rows(), and GiNaC::info_flags::symbol.

Referenced by inverse(), GiNaC::lsolve(), and GiNaC::sqrfree_parfrac().

unsigned GiNaC::matrix::rank ( ) const

Compute the rank of this matrix.

Definition at line 1091 of file matrix.cpp.

References col, fraction_free_elimination(), GINAC_ASSERT, and m.

Referenced by GiNaC::rank().

bool GiNaC::matrix::is_zero_matrix ( ) const

Function to check that all elements of the matrix are zero.

Definition at line 1542 of file matrix.cpp.

References m.

ex GiNaC::matrix::determinant_minor ( ) const [protected]

Recursive determinant for small matrices having at least one symbolic entry.

The basic algorithm, known as Laplace-expansion, is enhanced by some bookkeeping to avoid calculation of the same submatrices ("minors") more than once. According to W.M.Gentleman and S.C.Johnson this algorithm is better than elimination schemes for matrices of sparse multivariate polynomials and also for matrices of dense univariate polynomials if the matrix' dimesion is larger than 7.

Returns:
the determinant as a new expression (in expanded form)
See also:
matrix::determinant()

Definition at line 1125 of file matrix.cpp.

References GiNaC::_ex0, c, cols(), GiNaC::ex::expand(), GiNaC::is_zero(), m, n, r, and GiNaC::ex::swap().

int GiNaC::matrix::gauss_elimination ( const bool  det = false) [protected]

Perform the steps of an ordinary Gaussian elimination to bring the m x n matrix into an upper echelon form.

The algorithm is ok for matrices with numeric coefficients but quite unsuited for symbolic matrices.

Parameters:
detmay be set to true to save a lot of space if one is only interested in the diagonal elements (i.e. for calculating determinants). The others are set to zero in this case.
Returns:
sign is 1 if an even number of rows was swapped, -1 if an odd number of rows was swapped and 0 if the matrix is singular.

Definition at line 1245 of file matrix.cpp.

References GiNaC::_ex0, c, cols(), GiNaC::basic::ensure_if_modifiable(), GINAC_ASSERT, GiNaC::basic::info(), GiNaC::is_zero(), m, n, GiNaC::ex::normal(), GiNaC::info_flags::numeric, pivot(), r, and rows().

Referenced by determinant(), and solve().

int GiNaC::matrix::division_free_elimination ( const bool  det = false) [protected]

Perform the steps of division free elimination to bring the m x n matrix into an upper echelon form.

Parameters:
detmay be set to true to save a lot of space if one is only interested in the diagonal elements (i.e. for calculating determinants). The others are set to zero in this case.
Returns:
sign is 1 if an even number of rows was swapped, -1 if an odd number of rows was swapped and 0 if the matrix is singular.

Definition at line 1304 of file matrix.cpp.

References GiNaC::_ex0, c, cols(), GiNaC::basic::ensure_if_modifiable(), GINAC_ASSERT, m, n, pivot(), r, and rows().

Referenced by determinant(), and solve().

int GiNaC::matrix::fraction_free_elimination ( const bool  det = false) [protected]

Perform the steps of Bareiss' one-step fraction free elimination to bring the matrix into an upper echelon form.

Fraction free elimination means that divide is used straightforwardly, without computing GCDs first. This is possible, since we know the divisor at each step.

Parameters:
detmay be set to true to save a lot of space if one is only interested in the last element (i.e. for calculating determinants). The others are set to zero in this case.
Returns:
sign is 1 if an even number of rows was swapped, -1 if an odd number of rows was swapped and 0 if the matrix is singular.

Definition at line 1358 of file matrix.cpp.

References GiNaC::_ex0, GiNaC::_ex1, GiNaC::ex::begin(), c, cols(), GiNaC::divide(), GiNaC::basic::ensure_if_modifiable(), GiNaC::basic::expand(), GINAC_ASSERT, GiNaC::is_zero(), m, n, GiNaC::subs_options::no_pattern, GiNaC::ex::normal(), GiNaC::ex::numer_denom(), GiNaC::ex::op(), r, rows(), subs(), and GiNaC::ex::to_rational().

Referenced by determinant(), rank(), and solve().

int GiNaC::matrix::pivot ( unsigned  ro,
unsigned  co,
bool  symbolic = true 
) [protected]

Partial pivoting method for matrix elimination schemes.

Usual pivoting (symbolic==false) returns the index to the element with the largest absolute value in column ro and swaps the current row with the one where the element was found. With (symbolic==true) it does the same thing with the first non-zero element.

Parameters:
rois the row from where to begin
cois the column to be inspected
symbolicsignal if we want the first non-zero element to be pivoted (true) or the one with the largest absolute value (false).
Returns:
0 if no interchange occured, -1 if all are zero (usually signaling a degeneracy) and positive integer k means that rows ro and k were swapped.

Definition at line 1502 of file matrix.cpp.

References GiNaC::abs(), c, col, GiNaC::basic::ensure_if_modifiable(), GiNaC::basic::expand(), GINAC_ASSERT, GiNaC::numeric::is_zero(), GiNaC::is_zero(), k, m, and GiNaC::swap().

Referenced by division_free_elimination(), and gauss_elimination().

void GiNaC::matrix::print_elements ( const print_context c,
const char *  row_start,
const char *  row_end,
const char *  row_sep,
const char *  col_sep 
) const [protected]

Definition at line 146 of file matrix.cpp.

References col, m, row, and GiNaC::print_context::s.

Referenced by do_print(), do_print_latex(), and do_print_python_repr().

void GiNaC::matrix::do_print ( const print_context c,
unsigned  level 
) const [protected]

Default output to stream.

Reimplemented from GiNaC::basic.

Definition at line 162 of file matrix.cpp.

References print_elements(), and GiNaC::print_context::s.

void GiNaC::matrix::do_print_latex ( const print_latex c,
unsigned  level 
) const [protected]

Definition at line 169 of file matrix.cpp.

References col, print_elements(), and GiNaC::print_context::s.

void GiNaC::matrix::do_print_python_repr ( const print_python_repr c,
unsigned  level 
) const [protected]

Python parsable output to stream.

Reimplemented from GiNaC::basic.

Definition at line 176 of file matrix.cpp.

References print_elements(), and GiNaC::print_context::s.


Member Data Documentation

unsigned GiNaC::matrix::row [protected]
unsigned GiNaC::matrix::col [protected]

The documentation for this class was generated from the following files:

This page is part of the GiNaC developer's reference. It was generated automatically by doxygen. For an introduction, see the tutorial.