vecmatdocs.txt

Use of the Vector and Matrix C++ Classes
by D. House, 4/22/97

Copyright (C) - Donald H. House. 2005

GETTING STARTED
===============

To make use of the Vector and Matrix classes, transfer the Vector.h,
Vector.cpp, Matrix.h, Matrix.cpp, Utility.h and Utiltiy.cpp files to
your working directory. Make a Makefile for your project using the 
provided Makefile as a model.

Edit the symbol PROJECT to be the name of your main program.

Besides the main program, each separately compiled module for your
program needs to have an entry in the Makefile to make its .o file,
and also needs an entries in the OFILES and HFILES symbol definitions.

ACCESSING MATRICES AND VECTORS IN YOUR PROGRAMS
===============================================

Any program that makes use of the Matrix and Vector classes needs to
have the line:

#include "Matrix.h"

at the top. If a program uses only vectors but no matrices you can use
the line:

#include "Vector.h"

Also, you can remove any reference to Matrix from the Makefile

DEFINED CONSTANTS
=================

The following constants are defined and can be used in your program

SMALLNUMBER	1.0e-5
HUGENUMBER	1.0e10
PI 		3.1415926535897
RAD2DEG 	(180/PI)
DEG2RAD 	(PI/180)

UTILITY MACROS
==============

The following procedures are implemented as macros, and can be used
wherever needed for any numeric type:

Abs(x)		Returns the absolute value of the number x
		
Sqr(x)		Returns the square of the number x

Min(x1, x2)	Returns the smaller of x1 and x2

Max(x1, x2)	Returns the larger of x1 and x2

Round(x, p)	Rounds x to p digits to the right of the decimal point.
		This works only if x is floating-point and p is integer.
		e.g. round(3.65432, 2) => 3.65, round(3.65432, 1) => 3.7
		     round(-3.65432, 1) => -3.7, round(1234.5, -1) => 1230.0

Sign(x)		Returns -1 if x is negative, +1 if x is positive or 0
Swap(x1, x2)	Swaps the contents of x1 and x2
ApplySign(x, y)	Returns the absolute value of x with the sign of y applied

DegToRad(x) 	Given an angle x specified in degrees, returns the
		equivalent angle specified in radians

RadToDeg(x) 	Given an angle x specified in radians, returns the
		equivalent angle specified in degrees

SPECIAL SIZE MATRICES AND VECTORS
=================================

Classes Vector2d, Matrix2x2; vector3d, Matrix3x3; and Vector4d,
Matrix4x4 are defined as special cases of the Matrix and Vector
classes. These also have all of the following methods defined, except
those that have to do with size.

VECTOR USAGE
============

Class name:
	Vector

Constructors:
	Vector(n)		n dimensional vector
	Vector(n, values)	n dimensional vector initialized to the n
				values contained in the array values
	Vector(x, y)		2 dimensional vector set to [x, y]
	Vector(x, y, z)		3 dimensional vector set to [x, y, z]
	Vector(x, y, z, w)	4 dimensional vector set to [x, y, z, w]

	Vector 			Vector with no size specified.  You must
				explicitly call setsize(n) to set the size
				before using.  You should generally avoid
				this.
Methods:
	setsize(n)		sets the vector to n dimensions.  You should
				generally avoid this.  Instead, use one of
				the non-default constructors
	int getn()		returns the dimension of the vector

	print()			print the vector
	print(w, p)		print the vector using field width w and 
				precision p
	
	set(values)		set n dimensional vector to the n
				values contained in the array values
	set(x, y)		set 2 dimensional vector to [x, y]
	set(x, y, z)		set 3 dimensional vector to [x, y, z]
	set(x, y, z, w)		set 4 dimensional vector to [x, y, z, w]

	double norm()		returns the norm of the vector
	double normsqr()	returns the square of the norm of the vector
	Vector normalize()	returns unit vector in direction of vector

Operations:

	The following show one way to access the components of
	the special vectors from 2d to 4d. Components can also be
	accessed by index as shown further below:
	Vector2d v2;
	Vector3d v3;
	Vector4d v4;
	v2.x, v2.y
	v3.x, v3.y. v3.z
	v4.x, v4.y, v4.z, v4.w

	Everything else below will work for all vector types.
	The examples are assuming we have the variables:
	Vector v(3), v1(3), v2(3);	
	double a;
	int i;

	indexing into a vector (returns ith component of vector):
	v[i]

	negation of a vector:
	-v

	vector sum and difference:
	v1 + v2, v1 - v2

	scalar multiply:
	a * v, v * a

	scalar divide:
	v / a

	dot product:
	v1 * v2

	cross product:
	v1 % v2

	test for equality:
	v1 == v2
	
	assignment:
	v1 = v2;
	
	output to an iostream
	cout << v1;

MATRIX USAGE
============

Class name:
	Matrix

Constructors:
	Matrix(m, n)		m x n dimensional matrix (m rows, n vectors)
	Matrix(m, n, coeffs)	m x n dimensional matrix initialized by
				the m * n coefficients in the array coeffs
	Matrix(a11, a12,	2 x 2 D matrix initialized to a11 ... a22
	       a21, a22)
	Matrix(a11, a12, a13,	3 x 3 D matrix initialized to a11 ... a33
	       a21, a22, a23,
	       a31, a32, a33)
	Matrix(a11, a12, a13, a14, 4 x 4 D matrix initialized to a11 ... a44
	       a21, a22, a23, a24,
	       a31, a32, a33, a34,
	       a41, a42, a43, a44)
	Matrix(M)		matrix that is a copy of the matrix M

	Matrix			Matrix with no size specified.  You must
				explicitly call setsize(m, n) to set the size
				before using.  You should generally avoid
				this.

Methods:
	setsize(m, n)		sets the matrix to m x n dimensions.  You
				should generally avoid this.  Instead, use
				one of the non-default constructors
	int nrows()		returns the number of rows in the matrix
	int ncols()		returns the number of columns in the matrix

	print()			print the matrix using field width 7 and 
				precision 3
	print(w, p)		print the matrix using field width w and 
				precision p

	set(coeffs)		matrix initialized by the m * n coefficients
				in the array coeffs
	set(a11, a12,		initialize 2 x 2 D matrix to a11 ... a22
	    a21, a22)
	set(a11, a12, a13,	initialize 3 x 3 D matrix to a11 ... a22
	    a21, a22, a23,
	    a31, a32, a33)
	set(a11, a12, a13, a14,	initialize 4 x 4 D matrix to a11 ... a22
	    a21, a22, a23, a24,
	    a31, a32, a33, a34,
	    a41, a42, a43, a44)

	identity()		sets matrix to identity matrix

	Matrix transpose()	returns the transpose of the matrix
	Matrix inv()		returns the inverse of the matrix

Operations:

	All examples are assuming we have the variables:
	Matrix M(3, 3), M1(3, 3), M2(3, 3);
	Vector v(3), v1(3), v2(3);
	double a;
	int i, j;

	indexing into a matrix (returns coefficient in row i, column j):
	v[i][j]

	matrix sum and difference:
	M1 + M2, M1 - M2

	matrix multiply:
	M1 * M2

	multiply of matrix times scaler
	a * M
	M * a

	multiply of matrix times vector
	M * v

	multiply of transpose of vector times matrix
	v * M

	outer product of two vectors (for 2 n-vectors returns n x n matrix)
	v1 & v2