cecmatrix.txt	Matrix Handling			Oct 16, 2012

Author:    Charles E. Campbell  <NcampObell@SdrPchip.AorgM-NOSPAM>
	       (remove NOSPAM from Campbell's email first)
Copyright: (c) 2007-2012 by Charles E. Campbell		cecmatrix-copyright
           The VIM LICENSE applies to cecmatrix.vim and cecmatrix.txt
           (see copyright) except use "cecmatrix" instead of "Vim"

	       No warranty, express or implied.  Use At-Your-Own-Risk.

==============================================================================
1. Contents				cecmatrix cecmatrix-contents

	1. Contents.................: cecmatrix-contents
	2. Cecmatrix Tutorial.......: cecmatrix-tutorial
	3. Cecmatrix Manual.........: cecmatrix-manual
	4. Cecmatrix History........: cecmatrix-history


==============================================================================
2. Cecmatrix Tutorial				cecmatrix-tutorial

	The cecmatrix plugin facilates doing basic matrix arithmetic using
	Vim's floating point capability (floating-point-format).

	First:
		vim cecmatrix.vba
		:so %
		:q

	These instructions will unpack cecmatrix and make this help available.

	Enter a matrix into your text:

		1 2 3
		4 5 4
		5 6 7

	Select matrix using visual mode (linewise-visual or
	blockwise-visual) and then type :MatSet A.  You'll see

		:'<,'>MatSet A

	The '<,'> are marks from your visual mode selection.

	Enter a second matrix into your text and select it:

		1      .5     .333333
		.5     .33333 .25
		.33333 .25    .2

	Type  :MatSet B.

	Then you may perform some matrix arithmetic with these:

		Ex. :Mat B'

	will append after the current line:

		1      .5     .333333
	        .5     .33333 .25
		.33333 .25    .2

	Note that the numbers are lined up; that's because I have
	the AlignMaps plugin; see

	   http://www.drchip.org/astronaut/vim/index.html#ALIGN
	   http://vim.sourceforge.net/scripts/script.php?script_id=1195

	If you don't have the AlignMaps plugin then the matrix will be
	computed but not necessarily aligned well.

	More:
		Ex. :Mat 1/(A+B)
		 -6.869820  -1.644310   4.151071
		  5.648700   1.960269  -3.772242
		  0.185367  -0.483616   0.338538

		Ex. :Mat A*B
		  2.999990  1.916660  1.433333
		  7.833320  4.666650  3.383332
		 10.333310  6.249980  4.566665

		Ex. :Mat 1/B
		   9.005314   -36.027201    30.025159
		 -36.028822   192.146752  -180.135463
		  30.027321  -180.138706   180.127898

	If a better approximation of 1/3 had been used, the last example
	would result in all integers (http://en.wikipedia.org/wiki/Hilbert_matrix).

==============================================================================
3. Cecmatrix Manual	cecmatrixman cecmatrixmanual cecmatrix-manual


Initializing A Matrix:
	:MatSet label [separator-pattern]

	Use visual block mode to select a matrix; by default, the matrix
	separators are considered to be blanks, but you may provide an optional
	separator spec.

		Ex.  10 200 3
		     4 5 6

	Then press

		Ex. :MatSet A

	This will create a Matrix named "A" insofar as cecmatrix is concerned;
	the matrix is stored in a variable named "g:MatA".

	If one uses V (linewise visual mode), be careful, as the last line
	will be used to determine the column extent (character wise) of the
	matrix being read.

	As an example of using the separator pattern:

		Ex. 1,2,3
		    4,5,6
		    (select the two rows) :MatSet A ,


Adding Two Matrices:
	:Mat label1 + label2

	After you've selected two matrices, you may add them using a function
	call:

		Ex. :Mat A+B
		Ex. :let g:MatC= cecmatrix#MatAdd("A","B")


Subtracting Two Matrices:
	:Mat label1 - label2

	After you've selected two matrices, you may subtract them using a
	function call:

		Ex. :Mat A-B
		Ex. :let g:MatC= cecmatrix#MatSub("A","B")


Multiplying Two Matrices:
	:Mat label1 * label2

	After you've selected two matrices, you may multiply them using a
	function call:

		Ex. C= A*B
		Ex. :let g:MatC= cecmatrix#MatMult("A","B")


Inverting A Matrix:
	:Mat 1/label1

	One may invert a square matrix using

		:Mat 1/A
		Ex. :let g:MatC= cecmatrix#MatInv("A")

	g:cecmatrix_eps :
	Inversion is done using single pivoting and Gaussian elimination;
	however, singular matrices cannot be inverted.  The logic to
	determine if a matrix is singular utilizes g:cecmatrix_eps, which
	the cecmatrix plugin has defaulted to be 1e-7.

Transposing Two Matrices:
	:Mat label'

	After you've selected two matrices, you may add them using a function
	call:

		Ex. :Mat C=A'
		Ex. :let g:MatC= cecmatrix#MatTpose("A")


Multiple Operations:

	One may perform multiple operations and group them with parentheses:

		Ex. :Mat 1/(A+B)
		Ex. :Mat A*(B+C)*c


Writing Out Matrices:
	:MatWrite label1 [label2 [label3 ...]]

	After you've generated some matrices, you may wish to write them into
	your file.  You may do so with the :MatWrite command:

		Ex. :MatWrite A B C

	Empty rows will be inserted into your file and the matrices written into
	them.

	You can also combine some of these operations:

		Ex. :Mat A'
		Ex. :MatWrite cecmatrix#MatTpose("A")

	As illustrated in the preceding example, a ":Mat" operation that does
	not include an assignment ("=") will also write its result after the
	cursor.

	The numbers written out will be aligned using the \anum map provided
	by AlignMaps (alignmap-anum) if that plugin happens to be available
	in your installation.

	Numbers that differ from integers by less than g:cecmatrix_eps will
	be transformed into integers using float2nr().

==============================================================================
4. Cecmatrix History				cecmatrix-history {{{1

  v1	Sep 20, 2007	* first release
	Jun 28, 2011	* supports inverse (ie. 1/A)
	Jun 28, 2011	* requires vim's floating point

==============================================================================
Modelines: {{{1
vim:tw=78:ts=8:ft=help:fdm=marker: