io Programmo 27

home *** CD-ROM | disk | FTP | other *** search

/ io Programmo 27 / IOPROG_27.ISO / SOFT / DRMATRIX.ZIP / DOC / DRMATRIX.DOC next >

Wrap

Text File | 1997-01-01 | 14.7 KB | 319 lines

──────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────── DOCTOR MATRIX Version 1.00 ──────────────────────────────────────────────────────────── Shareware Vector and Matrix Algebra Programming Package for C++ ──────────────────────────────────────────────────────────── PROGRAMMER'S GUIDE ──────────────────────────────────────────────────────────── by Zvika Ben-Haim ──────────────────────────────────────────────────────────── ──────────────────────────────────────────────────────────── INTRODUCTION ──────────────────────────────────────────────────────────── This document describes the most basic characteristics of the Doctor Matrix programming package, explained in an easy, straightforward manner. It is intended to get you started using Doctor Matrix, and is by no means a full description of the package, which includes over 50 vector and matrix functions. After you figure out the basic features described in this document, you may be interested in reading about advanced functions in the Function Reference. Dr. Matrix is a C++ programming package that allows the calculation of matrix and vector functions easily and painlessly. All of the calculations are transparent to the programmer, and are used, as much as possible, in the same way as arithmetic operations of standard data types. Supported vector operations include vector addition, multiplication of a vector by a scalar, vector products, and more. Supported matrix operations include addition, multiplication, matrix trace, matrix ranking, matrix inversion, finding stepped and canonized matrices and more. Dr. Matrix takes full advantage of the template facility supported by the ANSI C++ Standard, Release 3. This allows you to customize the matrix and vector classes for your own use. If you are looking for fast, efficient matrix calculations, you can define an integer matrix class. If you want accurate results, use double matrices, or even long double matrices. You can even combine the matrix class with any other numeric class, for example to create complex number matrices. The unregistered version allows you to create only int and float objects. STATUS OF THIS PROGRAM ──────────────────────────────────────────────────────────── This program is shareware. You are allowed to test it for a reasonable amount of time for evaluation purposes only. You are encouraged to copy the package to your friends, under the condition that you do not alter any part of it. If you intend to use Doctor Matrix for any purpose other than evaluation, you must register. You have two options for registering: The Economy Package costs a mere $15 and allows you to compile in memory models from Tiny to Medium, as well as use matrix and vector objects of standard data types (excluding high-precision floating-point types). Your other option is to purchase Doctor Matrix Pro, a $50 package that comes with complete commented source code, allows you to use all memory models from Tiny to Huge, allows you to create matrix and vector objects of all data types (including non-standard classes), and enables you to make your own modifications and enhancements to the source. You will also receive a free upgrade, should a newer version be released. If you find a mistake, have a suggestion for future versions, or just have a general comment, please don't hesitate to write to me. Also, if you have written any sort of extension to the Doctor Matrix package which you think others could use, please send it to me. If I find it useful, I will add it to the next version of Doctor Matrix, and you will receive a registered version (Economy Package) free of charge. This package is copyrighted 1996-1997 by Zvika Ben- Haim. All rights reserved. I can be contacted by e-mail at the following address: zvikabh@rotem.technion.ac.il. Remember it takes courage to reveal one's e-mail publicly like this, so please spare me your junk mail and flames, they will be deleted without being read. You can also visit my web site, where you can download some other shareware programs and packages that I wrote. The URL is http://t2.technion.ac.il/~s3498650/ SYSTEM REQUIREMENTS ──────────────────────────────────────────────────────────── Doctor Matrix contains a header file, DRMATRIX.HPP, which should be included in every module using the Doctor Matrix functions. It also contains a set of library files. One of these library files should be added to your project. The correct file to be added depends on the memory model you are using: DRMTRXT.OBJ for the Tiny memory model or DRMTRXS.OBJ for the Small memory model. The registered version of the program includes support for all memory models, including Medium, Compact, Large, and Huge. Doctor Matrix requires the inclusion of the standard ANSI C++ header file IOSTREAM.H and the standard ANSI C header file STDLIB.H. If they are not included before including DRMATRIX.HPP, Doctor Matrix will include these files automatically. It also requires the use of the sqrt() function, which is non-standard C/C++ but is almost always found in the MATH.H header file. If you are having trouble getting Doctor Matrix to run on your compiler, particularly if it is an old or non- standard compiler, refer to the Troubleshooting section later in this document. VECTORS: THE BASICS ──────────────────────────────────────────────────────────── A vector is an ordered set of one or more items of the same type. For instance, (3.0 2.3 1.9) is a vector of order 3 and of data type float. Vectors can be aligned vertically or horizontally, which simply means the numbers in the set can be written from left to right or from top to bottom. When creating a vector, you must know its order, the type of data items it contains, and its alignment. You then create the vector using the following command: Vector<float> my_vect(4,V_VERT); The `float' can be changed to any numeric data type, or any numeric class (see the section Matrices of Classes). The vector name my_vect can be replaced with any legal variable name. The number 4 specifies the order (the number of elements in the vector), and can be any integer from 1 up, assuming there is sufficient memory. Following the order, an optional alignment specification can follow in parentheses. The allowed alignment options are V_VERT for vertical alignment, and V_HORIZ for horizontal alignment. If no alignment mode is specified, the vector is assumed to be aligned horizontally (V_HORIZ). To access the vector elements, use parentheses containing the subscript. For instance, my_vect(3) = 1.2; cout << my_vect(4); The subscript operator [] has been avoided to emphasize the fact that, unlike C/C++ subscripts, vector subscripts are 1-based; that is, the first element is number 1 (rather that 0). This follows the mathematics convention, rather than the C/C++ convention. Vectors of the same size, type and alignment can be added to each other using the addition operator. The result is a vector of the same size, type and alignment, in which each element is the sum of the same element in each of the vectors. Likewise, a vector can be multiplied by a scalar (a variable of the same type as the elements in the vector). The resulting vector is of the same type, size and alignment, and each of its elements is the product of the original vector's respective element by the scalar. A "dot product" between two vectors can also be calculated. These and many more functions are described in the function reference. MATRICES: THE BASICS ──────────────────────────────────────────────────────────── Using matrices is basically just as easy as using vectors. To define a matrix, use the form: Matrix<float> my_matrix(3,4); Where "float" can be replaced by any numeric data type, my_matrix is the matrix name, and the two numbers represent the size of the matrix: the first is the number of rows and the second is the number of columns. To access an element, use the parenthesis operator (), for example: my_matrix(1,1) = -.09; Like vectors, matrix subscripts are 1-based: the first row is number 1 and the first column is number 1. Matrix addition and multiplication work just like addition and multiplication in standard data types; for instance, Z = M1 * M2; M1 = Z + M1; A detailed description of these and other matrix operators and functions is given in the reference. MATRICES OF CLASSES (Registered Version Only) ──────────────────────────────────────────────────────────── In most cases, using a standard data type will suffice for ordinary matrix operations. However, you may want to use matrices of user-defined numeric classes, such as matrices of complex numbers, matrices of extra-precision numbers, etc. This is done in the same way as defining a matrix of an ordinary data type; however, for the code to compile and run correctly, the class you use must support the following arithmetic operations: - Support for addition, subtraction, multiplication and division of class objects using overloaded operators, as well as support for the modification operators (+=, -=, etc.); - Support for assignment of class objects to class objects; - A constructor of the form X::X(int) or a similar constructor which enables integers to be assigned to class objects; - A function called sqrt() which receives one parameter of the class type, and returns the square root of the object, either as another object of that class or as a data type that can be cast to the class. THE NEXT STEP ──────────────────────────────────────────────────────────── You've only begun to explore the power of Doctor Matrix. There are many more features you can learn about. The sample programs that come with this package demonstrate many of them. You can find the source code for this programs in the EXAMPLES subdirectory. The DRMDEMO program is a straightforward demonstration of many of the features in Doctor Matrix. The SOLVER program is an example of the use of matrix arithmetic in solving linear equations. If you want specific information about a function or operator, look it up in the function reference. The reference contains specific infomration on the usage, purpose and exact effect of all operators and functions in the package. TROUBLESHOOTING ──────────────────────────────────────────────────────────── Doctor Matrix was designed and tested in the Borland C++ 3.1 IDE. As mentioned, it is fully compliant with other ANSI C++ Release 3 compilers. However, you may encounter the following difficulties when using it: Header File Won't Compile: Some old compilers do not support ANSI C++ Release 3. For example, Borland Turbo C++ versions 1.x and 2.x do not support this version. They are therefore incapable of handling Doctor Matrix classes. If you are using Borland C++ 3.x, see the section "Problems with Debugging". Header File Compiles Incorrectly: If you are using non-standard versions of the IOSTREAM.H and STDLIB.H header files, and experience problems due to the fact that Doctor Matrix attempts to include these files although they have already been included, add the following lines to your program before the directive which includes DRMATRIX.HPP: #define __IOSTREAM_H #define __STDLIB_H These directives tell Doctor Matrix not to attempt to include the header files, and are usually defined automatically within the header file. Problems with Displaying Errors: Doctor Matrix uses the standard error output stream to print out errors that occur during processing of various functions. These errors can almost always be avoided by sufficient input checking by the programmer. However, it is best to ensure that the standard error stream (cerr) is valid and can be used for output. In particular, Windows programmers and other GUI programmers should ensure that cerr is redirected to a valid output stream, such as an error log file. For information on how to do this, refer to your C++ manual. Memory Problems: Allocating large vectors or matrices, or many of them, may cause memory problems. Some tips for freeing up memory are listed in the list of errors in the Reference, under the error "Not enough memory to allocate matrix/vector." Problems with Debugging: Borland C++ 3.1 has serious problems with debugging programs with templates. This problem may occur in other Borland compilers as well. It is a bug in the compiler, and not in the Dr. Matrix package, so please yell at Borland, not at me. The effect of this bug is as follows: Borland C++ tends to incorrectly compile the module information into the executable. This information tells the compiler which module contained the source for the current statement being executed. The effect of this bug is that when stepping through a program, you may seem to jump into a different file than you actually are. The line numbers are still correct, so that you can still figure out where you really are, but it's a pain (I know; I had to do this a lot when I was debugging Dr. Matrix). This bug also causes Borland C++ to report compile-time errors as belonging to a different file than they actually are. Again, looking through the correct file containing the error, at the reported line causing the error, is a workaround to this problem. If All Else Fails... If you encounter a difficulty in your program and are convinced that it results from the Doctor Matrix classes, write to me. Describe the problem, and give code portions (not complete programs!) that illustrate the error. Indicate your OS name and version, compiler name and version, and anything else you think might help to explain when or why the problem occurs.