1.4 Documentation

To help you learn to use LAPACK.h++ quickly and easily, Rogue Wave provides several forms of documentation with this product, including:

This manual, the LAPACK.h++ User's Guide
A class reference, the LAPACK.h++ Reference
A build guide, the LAPACK.h++ Build Guide
A readme file

The User's Guide and Reference are provided in an HTML version with the product, and they are also available for purchase as a printed manual. The Visual Studio Edition CD also provides these manuals in Microsoft HTML Help format, and integrates them into the MSDN Library.

The User's Guide gives an overview of the LAPACK.h++ library, and instructions on how to use the classes. You are encouraged to read the entire User's Guide. Table 1 describes its organization and content:

Table 1 -- Organization of the User's Guide

Chapter	Content
Chapter 1, "User's Guide"	The chapter you are reading now. Provides an overview of the product, its features, documentation, and conventions, and technical support contact information.
Chapter 2, "Class Overview"	Describes the kinds of classes in LAPACK.h++. Provides tables giving the type and header file for each class.
Chapter 3, "Vectors and Matrices"	Describes the basic classes used to represent linear operators in LAPACK.h++.
Chapter 4, "Factorizations"	Describes how LAPACK.h++ uses factorizations to solve systems of linear equations.
Chapter 5, "Least Squares Factorizations"	Describes how LAPACK.h++ uses least squares factorizations to solve systems of linear equations.
Chapter 6, "Symmetric Eigenvalue Problems"	Describes how LAPACK.h++ solves symmetric eigenvalue problems with real numbers.
Chapter 7, "Nonsymmetric Eigenvalue Problems"	Describes how LAPACK.h++ solves nonsymmetric eigenvalue problems using objects representing Schur, Hessenberg, and balance decompositions.
Chapter 8, "Other Decompositions"	Describes the LAPACK.h++ classes for singular value, QR, and complete orthogonal decompositions.
Chapter 9, "Technical Notes"	Describes the function operator()(int, int) and the matrix helper classes.

The Class Reference contains an alphabetical listing of the C++ classes in the LAPACK.h++ library. It complements the information provided in the User's Guide with the technical detail you need for writing applications.

The Build Guide describes how to build the LAPACK.h++ library and applications that depend on LAPACK.h++. The build guide is available in online formats only, including PDF for ease of printing. Section 1.4.1, "Online Documentation," describes the location of the Build Guide.

Also available is the C++ Library Products General Build Guide, which provides basic guidance in building Rogue Wave C++ library products and the applications that depend on them. The General Guide contains a reference section that describes preprocessor macros and compiler flags used with Rogue Wave's libraries.

1.4.1 Online Documentation

The locations of your online documents depend on whether you install your product using the Software Parts Manager (SPM) or the Visual Studio Edition (VSE) installation method.

1.4.1.1 Software Parts Manager Installations

Table 2a -- Documentation locations (SPM installations)

Document	Location
readme file	<rw_root>\parts\lpk207<os>\docs\lapkread.doc
HTML documentation	Single-point access to Rogue Wave HTML documentation: `<rw_root>\htmldocs\index.html` General Build Guide: `<rw_root>\htmldocs\genbd\index.html` LAPACK.h++ documentation: Build Guide: `<rw_root>\htmldocs\lpk<ver>bd\index.html` User's Guide: `<rw_root>\htmldocs\lpkug\index.html` Class Reference: `<rw_root>\htmldocs\lpkref\index.html`
PDF (Build Guide only)	`<rw_root>\htmldocs\pdf\lpk<ver>bd.pdf`

1.4.1.2 Visual Studio Edition Installations

Visual Studio Edition installations offer two types of online documentation: standard HTML (.html documents) and Microsoft HTML Help (.chm documents). You are given a choice of what documentation to install, so, depending on your choice, you may not have all of the documentation listed below on your system. You can return to the Visual Studio Edition CD at any time to install or uninstall documentation.

The HTML Help documents are integrated into the MSDN Library, and can be viewed by selecting Help|Contents on the MSVC Help menu. They can also be viewed independent of the MSDN Library by double-clicking on the .chm file name in Explorer.

The variable <rw_common> in the location paths represents the system location of your Rogue Wave common data, a location you specify the first time you install a product off the Visual Studio Edition CD.

Table 2b -- Documentation locations (VSE installations)

Document	Location
readme file	`<rw_root>\lapack\readme.txt`
HTML documentation	Single-point access to Rogue Wave HTML documentation: `<rw_common>\docs\htmldocs\index.html` General Build Guide: `<rw_common>\docs\htmldocs\genbd\index.html` LAPACK.h++ documentation: Build Guide: `<rw_common>\docs\htmldocs\lpk<ver>bd\index.html` User's Guide: `<rw_common>\docs\htmldocs\lpkug\index.html` Class Reference: `<rw_common>\docs\htmldocs\lpkref\index.html`
HTML Help	View through the Visual Studio Help menu. Files located at: Build Guide: `<rw_common>\docs\msdocs\lpk<ver>bd.chm` User's Guide: `<rw_common>\docs\msdocs\lpkug.chm` Class Reference: `<rw_common>\docs\msdocs\lpkref.chm`
PDF (Build Guide only)	`<rw_common>\docs\pdf\lpk<ver>bd.pdf`

1.4.2 Assumptions

The LAPACK.h++ documentation assumes that:

You are familiar with C++ programming and object-oriented technology.
You have set up your environment for your compiler. If you need assistance with this step, please consult your compiler documentation.

In addition, this manual assumes that you have installed and built LAPACK.h++ and the required software listed in Section 1.3, "Software Requirements." If you need help performing this step, please see the Build Guide.

1.4.3 Typographic Conventions

This manual uses the following typographic conventions:

Table 3 -- Typographic conventions

Convention	Purpose	Example
`courier`	Directories, file names, examples, operating system commands, function names, and code.	the `c:\rwav` directory DoubleSkewMat R = S;
`<x>`	A variable in path or file name.	`<file_name>.cpp`
italic	Conventional uses, such as new terms and titles.	the intercept parameter User's Guide
bold	Conventional uses such as emphasis, and commands from an interface. Also used for Rogue Wave product names.	do this before that; the OK button LAPACK.h++
*bold italic*	Class names.	*RWSlice*

1.4.4 Class Naming Conventions

Most Rogue Wave classes begin with the prefix RW, as in RWSlice. Class names in LAPACK.h++ differ from most other Rogue Wave classes, however, in that each class name begins with its type. For example, DoubleBandMat is the name of the class that encapsulates a band matrix and uses double as its type. The classes FloatBandMat and DComplexBandMat also encapsulate a band matrix, but use the types float and DComplex, respectively. In the Class Reference, all three classes are described under the entry {TYPE}BandMat. You simply replace the word {TYPE} with one of the specific types listed in the entry to get the name of a class.

Please note that {TYPE}BandMat is not a class in itself; it is a convenient shorthand meaning "all the BandMat classes no matter what type they use." In the User's Guide, we also use BandMat as shorthand for "a BandMat object using any type."

In the names of some classes, the placeholders {SHAPE} and {METHOD} are used much like {TYPE}. For example, under the Class Reference entry {TYPE}{SHAPE}Fact, you will find FloatSymFact, which means "the class that encapsulates a factorization of a symmetric matrix and uses float as its type." Under the entry {TYPE}LeastSq{METHOD}, you will find FloatLeastSqCh, which means "the class that encapsulates a least squares factorization object, uses float as its type, and the Cholesky method as its method."

The complete options for {TYPE}, {SHAPE}, and {METHOD} are explained in the Synopsis and Description for each entry in the Class Reference.

1.4.5 Function Naming Conventions

All function names begin with a lower case letter, with the first letter of subsequent words capitalized. Function names describe what a function does. For example, lowerBandwidth() returns the lower bandwidth of a matrix. Underline characters and abbreviations are not generally used in function names.

In the Class Reference entries for the LAPACK.h++ classes, public member functions also incorporate the names of their specific classes. For example, the lowerBandwidth() functions in the entry {TYPE}BandMat are called:

FloatBandMat::lowerBandwidth() for class FloatBandMat
DoubleBandMat::lowerBandwidth() for class DoubleBandMat
DComplexBandMat::lowerBandwidth() for class DComplexBandMat