A general description of OptiVec is given in HANDBOOK.HTM.
Chapter 1.2 of that file contains the licence terms for the Shareware version, Chapter 1.3 for the Registered version.
See FUNCREF.HTM for the description of individual VectorLib functions,
and CMATH.HTM for CMATH functions.
Contents
1. Introduction
1.1 Matrix Data Types
1.2 Prefixes of MatrixLib Functions
1.3 C/C++ Specifics
1.3.1 MatObj, the object-oriented interface for matrix functions
1.3.2 Direct-pointer form of matrix function calls
1.4 Pascal/Delphi Specifics
2. Management of Dynamically Generated Matrices
3. Initialization of Matrices
4. Data-Type Conversions
5. Transposing, Augmenting, Deleting, Extracting, and Filling Parts of a Matrix
6. Arithmetic Operations Performed on a Single Row, Column, or the Diagonal
7. Operations Performed Along All Rows or All Columns Simultaneously, or the Diagonal
8. Operations Involving Two Rows or Two Colums
9. Whole-Matrix Arithmetics: Addition, Multiplication
10. Linear Algebra
11. Eigenvalues and Eigenvectors, Matrix Square-Root
12. Two-Dimensional Fourier-Transform Methods
13. Data Fitting
13.1 Polynomials
13.2 General Linear Model Functions
13.3 Non-Linear Models
13.4 Fitting Multiple Data Sets
13.5 Helper Functions for Nonlinear Fits
14. Matrix Input and Output
15. Graphical Representation of Matrices
16. Alphabetical Reference for MatrixLib
1. Introduction
The MatrixLib part of OptiVec builds upon the principles established in the VectorLib part. You may wish to refer to the introductory chapters of HANDBOOK.HTM, before reading on for MatrixLib.
Back to Table of Contents
1.1 Matrix Data Types
As VectorLib defines vector data types, here are the matrix data types, defined in MatrixLib:
fMatrix | matrix of floats |
dMatrix | matrix of doubles |
eMatrix | matrix of extended (long double) |
cfMatrix | matrix of fComplex (complex<float>) |
cdMatrix | matrix of dComplex (complex<double>) |
ceMatrix | matrix of eComplex (complex<extended>) |
The ordering of elements is the same as in the two-dimensional arrays provided by the respective target compilers. This means that the matrices are stored row-wise in MatrixLib versions for C and C++ compilers, but column-wise in the Pascal/Delphi versions.
At present, integer matrices are defined, but no functions are available for them.
While we recommend to exclusively use these dynamically allocated matrix types, static matrices defined, e.g., as
float MX[4][6]; (for C/C++), or
MX: array[0..3][0..5] of Single; (for Pascal/Delphi)
can be used in all MatrixLib functions with the exception of the multiLinfit
and multiNonlinfit routines.
Back to Table of Contents
1.2 Prefixes of MatrixLib Functions
Each MatrixLib function has a prefix defining the data type on which it acts:
Prefix: | Arguments: |
MF_ | fMatrix, float and fVector |
MD_ | dMatrix, double and dVector |
ME_ | eMatrix, extended (long double) and eVector |
MCF_ | cfMatrix, fComplex and cfVector |
MCD_ | cdMatrix, dComplex and cdVector |
MCE_ | ceMatrix, eComplex and ceVector |
In a few cases, the prefix is augmented by a three-letter code denoting special matrix properties:
- MFdia_ means that the function expects a diagonal matrix (i.e., a square matrix which has non-zero elements only on the diagonal); as there is no sense in storing all the zeros, diagonal matrix are actually stored as vectors, holding only the diagonal elements.
- MFsym_ denotes a function which expects the input matrix to be symmetric. At present, only MFsym_eigenvalues and MFsym_sqrt make use of this assumption.
- MFtrd_ means the function is for a tridiagonal matrix (i.e., a square matrix with non-zero elements only on the diagonal plus or minus one column). A tridiagonal matrix has to be entered in the form of a matrix with three rows, representing the three vectors actually containing non-zero data. In other words, the original matrix
d0 | u0 | 0 | ··· | | |
l1 | d1 | u1 | 0 | ··· | |
0 | l2 | d2 | u2 | 0 | ··· |
| | | ··· | | |
| | | lN-2 | dN-2 | uN-2 |
| | | 0 | lN-1 | dN-1 |
is compacted into the form
u0 | u1 | u2 | ··· | uN-2 | * |
d0 | d1 | d2 | ··· | dN-2 | dN-1 |
* | l1 | l2 | ··· | lN-2 | lN-1 |
The elements l0 and uN-1, marked with an asterisk, are undefined and never used.
Back to Table of Contents
1.3 C/C++ Version Specifics
1.3.1 MatObj, the object-oriented interface for matrix functions
Similarly to the vector objects of VecObj, the object-oriented interface for the matrix functions is contained in the include-files <fMatObj.h>, <dMatObj.h> etc., with one include-file for each of the data-types supported in OptiVec. Remember that, in order to get the whole interface (for all data types at once),
#include <OptiVec.h>.
For access to any of the vector graphics functions, always include <OptiVec.h>.
By analogy with the alias names of the vector objects, the matrix objects get the alias names fMatObj, dMatObj, and so on, with the data-type signalled by the first one or two letters of the class name.
The matrix constructors are:
matrix(); // no memory allocated, dimensions set to 0
matrix( unsigned ht, unsigned len ); // ht by len matrix allocated
matrix( unsigned ht, unsigned len, T fill ); // as before, but initialized with value "fill"
matrix( matrix <T> init ); // creates a copy of the matrix "init"
For the matrix classes, the arithmetic operators
+ - * += -= *=
are defined.
While the vector-vector operator * refers to element-wise multiplication, the matrix-matrix, vector-matrix, or matrix-vector operator * means true matrix-matrix or matrix-vector multiplication.
If you ever need to process a MatObj matrix in a "classic" plain-C OptiVec function, you may use the member functions
getHt() and getLen() to retrieve the matrix dimensions,
getMatrix to obtain the actual matrix pointer of the data type fMatrix etc., or
getM0 for the vector M[0] of the data type fVector etc., which is actually a pointer to the first matrix element.
The syntax of all MatObj functions is described below together with
the basic MatrixLib functions for which tMatObj serves as a wrapper.
Please note the following restrictions, coming from the tight control of matrix dimensions for compatibility:
- With the "normal" MF_ functions, one can use some large matrix as working space for
matrices of smaller dimensions. As long as one does not access individual elements or rows, but uses only whole matrices, this allows to use one and the same working space, say for an [n * n] and an [m * n] matrix (m < n: neglect one or more rows). This is not possible in MatObj, where the matrix dimensions are encapsulated, and no distinction between "actual" and "used" dimensions can be made.
- It is not even possible to overwrite, e.g., a non-square matrix with its transpose, even if you were willing to sacrifice the row pointers, and even if the number of matrix elements obviously stays the same.
- All MatObj Dia_... functions require square matrices (ht = len), whereas MF_Dia_... functions work, in principle, with non-square matrices, as long as the parameter "len" in the function call corresponds to the smaller dimension.
- The multifit functions are not encapsulated, as the VF_EXPERIMENT and MF_EXPERIMENT structures need pointers rather than objects anyway.
1.3.2 Direct-pointer form of matrix function calls
In the C/C++ version of MatrixLib, all functions taking matrix arguments exist in a second form. In this form, all matrix arguments are replaced by pointers to the first elements of the respective matrices. You can explicitly use the second form by leaving away the underbar of the function-name prefix. Calling
MF_mulM( MC, MA, MB, htA, lenA, lenB );
is equivalent to calling
MFmulM(&(MC[0][0]),&(MA[0][0]),&(MB[0][0]),htA,lenA,lenB); or
MFmulM( MC[0], MA[0], MB[0], htA, lenA, lenB );
Actually, the run-time routines are in the second form, and the MatObj member functions as well as the macros defined in <MFstd.h> etc. convert calls to the first form into calls to the second form.
Back to Table of Contents
1.4 Pascal/Delphi Version Specifics:
In the Pascal/Delphi version of MatrixLib, matrices of all data types are actually defined as pointers to the element M[0][0]. This means you can pass static matrices (like MX: array[0..5][0..5] of Single; ) to MatrixLib functions with the address operator:
MF_equ1( @(MX[0][0]), 6 );
Delphi only:
From version 4 on, Delphi offers dynamic arrays. In the one-dimensional case, they are declared as "array of Single", "array of Double", etc. The VecLib unit includes short-cut definitions for these types as fArray,
dArray, etc. By simply type-casting fArrays into fVectors, they can be used with all VectorLib functions.
The situation is more complicated in the two-dimensional case. Dynamic two-dimensional arrays can be created in Delphi by declaring them as "array of fArray", "array of dArray", etc. Short-cut definitions for these types are also given in the VecLib unit, as f2DArray, d2DArray, etc. As a consequence of the described way of defining 2D-Arrays in Delphi, each row of a matrix is stored in a separate vector. This means that the matrix elements do no longer occupy a single, contiguous memory space. Therefore, 2DArrays cannot be used directly with MatrixLib functions.
Instead, they have to be copied into matrices by calling MF_2DArrayToMatrix etc., before MatrixLib functions can be used on them. The reverse conversion is available as MF_MatrixTo2DArray.
In the following chapters, a brief summary of all MatrixLib function is given, ordered into groups according to their functionality. At the end of this file, chapter 16 describes all MatrixLibfunctions in alphabetical order.
Back to Table of Contents
2. Management of Dynamically Generated Matrices
MF_matrix | allocate memory for a matrix |
MF_matrix0 | allocate memory and set all elements 0 |
M_free | free one matrix (data-type independent) |
M_nfree | free n matrices (data-type independent; only C/C++) |
V_freeAll | free all existing vectors and matrices |
OptiVec's dynamically allocated matrices are aligned on 32-byte boundaries, which allows for optimum cache-line matching for the Pentium processor and its currently available successors and competitors.
C/C++ version only:
OptiVec's dynamically allocated matrices can be addressed just like two-dimensional static arrays of C/C++. If you have, e.g., an fMatrix X; and a variable float a;, you can write a line like
a = MX[3][5];
Both C/C++ and Pascal/Delphi versions:
There are two functions addressing single elements. These functions are the only means to address elements in Pascal/Delphi, and are also needed for getting around the pointer arithmetics bug in some versions of Borland C++:
To assign a value to a specific matrix element, you should use the syntax
*(MF_Pelement( MX, ht, len, 3, 4 )) = 3.0; /* for C/C++*/
MF_Pelement( MX, ht, len, 3, 4 )^ := 3.0; (* for Pascal/Delphi *)
Back to Table of Contents
3. Initialization of Matrices
In order to initialize all matrix elements with the same value, or to perform the same arithmetic operation on all matrix elements simultaneously, please use the respective VectorLib function. You can do so, because all matrices are in fact stored as vectors, occupying a contiguous space in memory. All you have to do is to pass the first row of the matrix (rather than the matrix itself) to the vector function. Fore example, you can initialize all matrix elements with a constant C by calling
VF_equC( MA[0], ht*len, C ); /* C/C++ */
VF_equC( MA, ht*len, C ); (* Pascal/Delphi *)
As you shall see, some of the most common operations of this kind are also explicitly defined in MatrixLib, like initialization with zero, MF_equ0, or multiplication by a constant, available as MF_mulC (see chapter 9). Here are the typical matrix initialization functions:
MF_equ0 | set all elements to 0 |
MF_equ1 | identity matrix: set all diagonal elements to 1.0, all others to 0 |
MF_equm1 | negative identity matrix: set all diagonal elements to -1.0, all others to 0 |
MF_random | fill with random numbers |
MF_outerprod | matrix formed by the "outer product" of two vectors |
MF_Row_equ0 | set all elements of one specific row to 0 |
MF_Col_equ0 | set all elements of one specific column to 0 |
MF_Dia_equ0 | set all diagonal elements to 0 |
MF_Row_equC | set all elements of one specific row to the constant C |
MF_Col_equC | set all elements of one specific column to the constant C |
MF_Dia_equC | set all diagonal elements to the constant C |
MF_Row_equV | copy a vector into one specific row |
MF_Col_equV | copy a vector into one specific column |
MF_Dia_equV | copy a vector into the diagonal |
MF_Trd_equM | copy a compacted tridiagonal matrix into a general matrix |
MF_equM | make one matrix the copy of another |
MF_neg | make one matrix the negative of another |
MCF_conj | make one matrix the complex conjugate of another |
MCF_hermconj | make one matrix the Hermitian conjugate of another: MB = MAT* |
MF_UequL | copy lower-diagonal elements into upper-diagonal by index-reflection, so as to get a symmetric matrix |
MF_LequU | copy upper-diagonal elements into lower-diagonal |
Two-dimensional windows for spectral analysis are provided by:
Back to Table of Contents
4. Data-Type Conversions
Matrices of every data type can be converted into every other. Only a few examples are given; the rest should be obvious.
M_FtoD | fMatrix to dMatrix |
M_EtoD | eMatrix to dMatrix (with overflow protection) |
M_CDtoCF | cdMatrix to cfMatrix (with overflow protection) |
M_DtoE | dMatrix to eMatrix |
Back to Table of Contents
5. Transposing, Augmenting, Deleting, Extracting, and Filling Parts from a Matrix
Note that, in contrast to the VectorLib functions VF_insert and VF_delete, insertion and deletion of rows or columns of matrices is not done in-place. Rather, the MF_Row_insert etc. store the augmented or truncated input matrix MA in an output matrix MB. If augmenting, be sure that MB is large enough to accommodate the enlarged output matrix! Normally, this means that you have to create a new matrix MB before calling MF_???_insert and possibly discarding MA by calling
M_free( MA ); afterwards.
If this process is repeated more often, you might wish to avoid the inefficiency of these "create new" - "copy" - "delete old" cycles. In this case, you can create MA from the outset with the maximum dimensions that will eventually be reached (or, if these are not known beforehand, with the upper limits of both ht and len). During the build-up process then, you have to keep track of the actual dimensions and use these (not the maxima
used for allocation!) in all MatrixLib function calls. Now you may overwrite the original matrix by the augmented one in each call to MF_???_insert as, e.g., in:
MF_Row_insert( MA, MA, actualhtA+1, actuallenA+1, 0, X );
C++ with dynamic matrices only:
If you overwrite MA by MB in the column insertion/deletion functions, you lose the possibility of accessing individual matrix elements by writing MB[i][j]. This is no longer possible, as the row pointers of the output matrix will still remain those of the input matrix. Then, you can only use MF_element and MF_Pelement to access individual elements. If you are exclusively inserting/deleting rows rather than columns, on the other hand, the row pointers remain valid.
Back to Table of Contents
6. Arithmetic Operations Performed on a Single Row, Column, or the Diagonal
MF_Row_addC | add a constant to all elements of a specific row |
MF_Col_addC | add a constant to all elements of a specific column |
MF_Dia_addC | add a constant to all diagonal elements |
MF_Row_addV | add corresponding vector elements to all elements of a specific row |
MF_Col_addV | add corresponding vector elements to all elements of a specific column |
MF_Dia_addV | add corresponding vector elements to the diagonal elements |
A few examples should suffice for the other functions of this family:
MF_Row_subC | subtract a constant from all elements of a specific row |
MF_Col_subrC | reverse substraction: difference between column elements and a constant |
MF_Dia_mulV | multiply the diagonal elements with corresponding vector elements |
MF_Row_divV | divide all elements of a specific row by corresponding vector elements |
MF_Col_divrC | reverse division: division of a constant by the individual column elements |
Back to Table of Contents
7. Operations Performed Along All Rows or All Columns Simultaneously, or Along the Diagonal of a Square Matrix
Please note that multiplying all rows or all columns by one and the same vector is equivalent to a multiplication by a diagonal matrix, which is provided by MF_mulMdia and MF_TmulMdia.
For all of the above functions involving maxima (...max, ...absmax), the corresponding minima are found by the functions named ...min, ...absmin.
For complex numbers, maxima can be defined by various criteria. The following table summarizes the functions finding them (again, of course, the corresponding functions for the minima exist as well):
MCF_Rows_absmax | store the maxima of the absolute values of all rows in a (real-valued) column vector |
MCF_Cols_absmax | store the maxima of the absolute values of all colums in a (real-valued) row vector |
MCF_Dia_absmax | return the maximum of the absolute values of the diagonal elements as a (real) scalar |
MCF_Rows_absmaxReIm | find the maximum absolute values of all real and of all imaginary parts separately along the rows of a matrix; merge the maxima into complex numbers, and store them in a column vector |
MCF_Cols_absmaxReIm | find the maximum absolute values of all real and of all imaginary parts separately along the columns of a matrix; merge the maxima into complex numbers, and store them in a row vector |
MCF_Dia_absmaxReIm | find the maximum absolute values of all real and of all imaginary parts separately along the diagonal of a square matrix; merge these two maxima into one complex number and return it as a scalar |
MCF_Rows_cabsmax | find the complex numbers of largest magnitude along rows and store these row maxima in a (complex) column vector |
MCF_Cols_cabsmax | find the complex numbers of largest magnitude along columns and store these column maxima in a (complex) row vector |
MCF_Dia_cabsmax | find the complex number of largest magnitude along the diagonal of a square matrix and return it as a (complex) scalar |
MCF_Rows_maxReIm | find the maxima of all real and of all imaginary parts separately along the rows of a matrix; merge the maxima into complex numbers, and store them in a column vector |
MCF_Cols_maxReIm | find the maxima of all real and of all imaginary parts separately along the columns of a matrix; merge the maxima into complex numbers, and store them in a row vector |
MCF_Dia_maxReIm | find the maximum of all real and of all imaginary parts separately along the diagonal of a square matrix; merge these two maxima into one complex number and return it as a scalar |
MCF_Rows_sabsmax | find the complex numbers of largest sum |Re|+|Im| along rows and store these row maxima in a (complex) column vector |
MCF_Cols_sabsmax | find the complex numbers of largest sum |Re|+|Im| along columns and store these column maxima in a (complex) row vector |
MCF_Dia_sabsmax | find the complex number of largest sum |Re|+|Im| along the diagonal of a square matrix and return it as a (complex) scalar |
Back to Table of Contents
8. Operations Involving Two Rows or Two Colums
Back to Table of Contents
9. Whole-Matrix Arithmetics: Addition, Multiplication
a) Element-wise operations
MF_addM | add two matrices |
MF_addMT | add one matrix and the transpose of another matrix
MC = MA + MBT |
MF_subM | subtract one matrix from another |
MF_subMT | subtract a transposed matrix
MC = MA - MBT |
MF_subrMT | subtract a matrix from another, transposed, matrix
MC = MBT - MA |
MF_mulC | multiply all matrix elements by a constant |
MCF_mulReC | multiply all elements of a complex matrix by a real number |
MF_divC | divide all matrix elements by a constant |
MCF_divReC | divide all elements of a complex matrix by a real number |
MFs_addM | scaled addition of two matrices:
MC = c * (MA + MB) |
MFs_addMT | scaled addition of one matrix and the transpose of another: MC = c * (MA + MBT) |
MFs_subM | scaled subtraction of two matrices:
MC = c * (MA - MB) |
MFs_subMT | scaled subtraction of one matrix and the transpose of another: MC = c * (MA - MBT) |
MFs_subrMT | scaled reverse subtraction of one matrix and the transpose of another: MC = c * (MBT - MA) |
MF_lincomb | linear combination:
MC = ca * MA + cb * MB |
b) Matrix multiplication:
MF_mulV | multiply a matrix by a column vector:
Y = MA * X |
MF_TmulV | multiply the transpose of a matrix by a column vector:
Y = MAT * X |
VF_mulM | multiply a row vector by a matrix:
Y = X * MA |
VF_mulMT | multiply a row vector by the transpose of a matrix:
Y = X * MAT |
MF_mulM | multiply two matrices:
MC = MA * MB |
MF_mulMT | multiply one matrix by the transpose of another matrix:
MC = MA * MBT |
MF_TmulM | multiply the transpose of a matrix by another matrix:
MC = MAT * MB |
MF_TmulMT | multiply the transpose of one matrix by the transpose of another matrix:
MC = MAT * MBT |
MCF_mulMJ | multiply one matrix by the hermitian conjugate of another matrix:
MC = MA * MBT * |
MCF_HmulM | multiply the hermitian conjugate of a matrix by another matrix:
MC = MAT * * MB |
c) Multiplications of general matrices by diagonal matrices or vice versa
The diagonal matrix is passed to the respective function as a vector.
MF_mulMdia | multiply a general matrix by a diagonal matrix:
MC = MA * MBDia |
MF_TmulMdia | multiply the transpose of a matrix by a diagonal matrix:
MC = MAT * MBDia |
MFdia_mulM | multiply a diagonal matrix by a general matrix:
MC = MADia * MB |
MFdia_mulMT | multiply a diagonal matrix by the transpose of a general matrix:
MC = MADia * MBT |
Back to Table of Contents
10. Linear Algebra
There are three groups of linear algebra functions. The first group consists of "easy-to-use" versions which can be used as black-box functions without caring about their internal working. The second group consists of functions
for LU decomposition and its applications. The third group, finally, is devoted to Singular Value Decomposition (SVD). Except for the functions based on SVD, the linear algebra functions are available both for real and for complex matrices.
Here are the "easy-to-use" versions of linear algebra functions:
MF_solve |
solve simultaneous linear equations (using LU decomposition) |
MF_inv | invert a matrix |
MF_det | determinant of a matrix |
MF_solveBySVD | solve simultaneous linear equations, using Singular Value Decomposition |
MF_safeSolve | tries first solution by LUD; if that fails, SVD is done |
Now some functions for explicit LU decomposition and for treatment of LU decomposed matrices:
Singular Value Decomposition and related functions are offered as:
Back to Table of Contents
11. Eigenvalues and Eigenvectors, Matrix Square-Root
At present, only the special, but most frequent case of symmetric real matrices is covered:
MFsym_eigenvalues |
eigenvalues with or without eigenvectors of a symmetric real matrix |
MFsym_sqrt |
square-root of a symmetric, positive definite matrix |
Back to Table of Contents
12. Two-Dimensional Fourier-Transform Methods
By analogy with the corresponding one-dimensional Fourier Transform methods described in the VectorLib handbook, the following functions for the two-dimensional case are available in MatrixLib:
MF_FFTtoC | Forward Fast Fourier Transform (FFT) of a real matrix; the result is a cartesian complex matrix |
MF_FFT | Forward and backward FFT of real matrices; using symmetry relations, the complex result is packed into a real matrix of the same size as the input matrix |
MCF_FFT | Forward and backward FFT of complex matrices |
MF_convolve | Convolution with a spatial response function |
MF_deconvolve | Deconvolution |
MF_filter | Spatial filtering |
MF_autocorr | Spatial autocorrelation |
MF_xcorr | Spatial cross-correlation |
MF_spectrum | Spatial frequency spectrum |
Back to Table of Contents
13. Data Fitting
MatrixLib provides a broad range of data fitting functions for various classes of model functions. Let us first show you an overview over the available functions, before we describe the various classes of model functions and their treatment in OptiVec fitting functions in detail.
Now let us have a look at the various classes of model functions. The most simple one is a straight line,
Yi = a * Xi + b;
Fitting Y = f(X) data to a straight line is called "linear regression" and accomplished by VF_linregress.
The next level of sophistication are polynomials, described in the following paragraph:
13.1 Polynomials
Polynomials are functions of the form
Yi = a0 + a1Xi + a2Xi2 ... anXin
Just as linear regression, polynomial fitting is available for Y-X data (VF_polyfit), but not for MZ=f(X,Y) data. In polynomial fitting, you are interested in the coefficients ai up to a certain limit, the degree n of the polynomial. In the simplest form, all coefficients are treated as free parameters, without the possibility of "fixing" those whose values you happen to know beforehand. Polynomial fitting is most useful for degrees of 2 to 4. With degrees higher than 5, you will be able to fit almost any data - but the resulting coefficients will be at best inaccurate and at worst useless, as already very little experimental noise will strongly influence the balance of the higher terms. If you do need polynomials of higher degrees, you should carefully examine your problem to see which terms you can eliminate. This leads us from polynomials to the next class of fitting functions, namely:
13.2 General Linear Model Functions
In the general linear case, you have to write the model function yourself and pass it as an argument to the fitting routine. The word "linear" means that the model function consists of a linear combination of basis functions each of which depends linearly on the fitting coefficients:
y = a0f0(x) + a1f1(x) + a2f2(x)...
The individual functions fi(x) may be non-linear in x, but not in the coefficients ai. For example,
y = a0sin(x)+ a1cos(x)
is a valid linear fitting function, but
y = sin(a0x)+ cos(a1x)
is not.
|
Pascal with DOS only:
The module, containing the model function to be passed to VF_linfit, must be compiled using the "Force Far Calls" option (Options/Compiler in the IDE or switch {$F+} ) ! |
For general linear fits, the model function has to be provided in a form which calculates the individual basis functions for each x-value present in the data set. The above example with sine and cosine functions would be coded in C/C++ as
void LinModel( fVector BasFuncs, float x, unsigned nfuncs )
{
BasFuncs[0] = sin(x);
BasFuncs[1] = cos(x);
}
Note that the coefficients ai are not used in the model function itself. The argument nfuncs (which is neglected in the above example) allows to use a variable number of basis functions. It is also possible to switch fitting parameters "on" and "off", i.e., "free" or "fixed". To this end, the routine VF_linfit takes a "status" array as an argument. For all members of the parameter vector that are to be treated as free, the corresponding "status" entry must be set to 1. If statusi is set to 0, the corresponding parameter, ai, is treated as fixed at its value upon input.
Internally, VF_linfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are
set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
Having noted above that functions like
y = sin(a0x)+ cos(a1x)
require their own treatment, we arrive at the last and most general class of model functions:
13.3 Non-Linear Models
As described above, fits to linear model functions (which include, of course, simple polynomials) are performed internally by solving a set of coupled linear equations - which is basically a simple matrix inversion process. The situation for non-linear model functions is completely different: no closed-form solution exists, and the fitting problem can be solved only iteratively. Therefore, fitting to non-linear models is much more time-consuming (by 3-5 orders of magnitude!) than fitting to linear models. Two non-linear fitting algorithms are offered:
- the Levenberg-Marquardt method, and the
- Downhill-Simplex method by Nelder and Mead.
As a starting-point, it is normally a good idea to choose a combination of both (choose FitOptions.LevelOfMethod = 3, see below).
The fundamental difference between linear and non-linear data fitting is reflected also in the required formulation of the model functions. In contrast to the linear case, here it is not the individual basis functions which are needed. Rather, the model function will be called by VF_nonlinfit with the whole X-vector as input argument and has to return the whole Y-vector. For the above non-linear sine and cosine example, this could be coded in C/C++ as
void NonlinModel( fVector Y, fVector X, ui size)
{
for( ui i=0; i<size; i++ )
Y[i] = sin( a[0]*X[i] ) + cos( a[1]*X[i] );
}
Keeping in mind that a nonlinear fitting routine will spend most of its time in your model function (and its derivatives, see below), you might wish to optimize this function, using vector functions. Suppose you have declared and allocated the fVector YHelp somewhere within your main program. Then you can write:
void OptNonlinModel( fVector Y, fVector X, ui size)
{
VFx_sin( YHelp, X, size, a[0], 0.0, 1.0 );
VFx_cos( Y, X, size, a[1], 0.0, 1.0 );
VF_addV( Y, Y, YHelp, size );
}
The parameter array "a" should be global. It is passed as an argument to VF_nonlinfit, and its elements are changed during the fitting process. Upon input, "a" must (!) contain your initial "best guess" of the parameters. The better your guess, the faster VF_nonlinfit will converge. If your initial
guess is too far off, convergence might be very slow or even never attained.
All nonlinfit functions return the figure-of-merit of the best parameter array "A" found. To perform the fit, these functions need not only the fitting function itself, but also its partial derivatives with respect to the individual coefficients. Therefore, an argument "Derivatives" is required in calling the nonlinfit functions. If you happen to know the partial derivatives analytically, Derivatives should point to a function calculating them. If you do not know them, call with Derivatives = NULL (nil in Pascal/Delphi). In the latter case, all derivatives will be calculated numerically inside the functions. In cases where you know some, but not all of the partial derivatives of Y with respect to the coefficients ai, you could also calculate dY / dai wherever you have an analytic formula, and call VF_nonlinfit_autoDeriv for the remaining coefficients. To demonstrate this possibility, here is a function coding the derivatives for our non-linear sine and cosine example:
void DerivModel( fVector dYdAi, fVector X, ui size, unsigned iPar )
{
switch( iPar )
{
case 0:
for( ui i=0; i<size; i++ )
dYdAi[i] = X[i] * cos( a[0]*X[i] );
break;
case 1: /* say we don't know this derivative: */
VF_nonlinfit_autoDeriv( dYdAi, X, size, iPar);
}
}
Think twice, however, before resorting to VF_nonlinfit_autoDeriv: The function calls needed to determine the derivatives numerically may easily slow down your fit by a factor of 3 to 5! Anyway, as described above for the model function itself, also its derivatives should be implemented using vector functions. This leads us finally to the optimized version of the derivatives function:
void OptDerivModel( fVector dYdAi, fVector X, ui size, unsigned iPar )
{
switch( iPar )
{
case 0:
VFx_cos( dYdAi, X, size, a[0], 0.0, 1.0 );
VF_mulV( dYdAi, dYdAi, X, size ); break;
case 1:
VFx_sin( dYdAi, X, size, a[1], 0.0, -1.0 );
VF_mulV( dYdAi, dYdAi, X, size );
}
}
For actual working examples for the polynomial, general linear, and general non-linear cases, please see FITDEMO.CPP, FITDEMOW.CPP, FITDEMOB.BPR, FITDEMO.PAS, or FITDEMO.DPR.
The nonlinear fitting routines are highly sophisticated and offer the user a lot of different options. These options may be set by the function V_setNonlinfitOptions. To retrieve current settings, use
V_getNonlinfitOptions.
All options are packed into a structure (struct in C/C++, record in Pascal/Delphi) named VF_NONLINFITOPTIONS.
It has the following fields:
int FigureOfMerit; | 0: least squares fitting
1: robust fitting, optimizing for minimum absolute deviation
(default: 0) |
float AbsTolChi; | absolute change of c2 (default: EPSILON) |
float FracTolChi; | fractional change of c2 (default: SQRT_EPSILON) |
float AbsTolPar; | absolute change of all parameters (default: SQRT_MIN) |
float FracTolPar; | fractional change of all parameters (default: SQRT_EPSILON)
The four xxxTolChi and xxxTolPar parameters describe the convergence conditions: if the changes achieved in successive iterations are smaller than demanded by these criteria, this signals convergence. Criteria
which are not applicable should be set to 0.0. |
unsigned HowOftenFulfill; | how often fulfill one of the above conditions before convergence is considered achieved (default: 3) |
unsigned LevelOfMethod; | 1: Levenberg-Marquardt method,
2: Downhill Simplex (Nelder and Mead) method,
3: both methods alternating;
add 4 to this in order to try breaking out of local minima;
0: no fit, calculate only c2 (and Covar)
(default: 1) |
unsigned LevMarIterations; | max.number of successful iterations of LevMar during one run (default: 100) |
unsigned LevMarStarts; | number of LevMar restarts per run (default: 2) |
float LambdaStart,
LambdaMin,
LambdaMax,
LambdaDiv,
LambdaMul; | treatment of LevMar parameter lambda (don't touch, unless you are an expert!) |
unsigned DownhillIterations; | max. number of successful iterations in Downhill Simplex method (default: 200) |
float DownhillReflection,
DownhillContraction,
DownhillExpansion; | treatment of re-shaping of the simplex in Downhill Simplex method (don't touch
unless you are an expert!) |
unsigned TotalStarts; | max. number of LevMar/Downhill pairs (default: 16) |
fVector UpperLimits, LowerLimits; | impose upper and/or lower limits on parameters. Default for both: NULL or nil |
void (*Restrictions)(void); | pointer to a user-defined function, implementing restrictions on the parameters which cannot be formulated as simple upper/lower limits. The function must check the whole parameter vector and edit the parameters as needed. Default: NULL or nil. |
13.4 Fitting Multiple Data Sets
In addition to the fitting functions for single data sets, there are routines for fitting multiple data sets simultaneously. Say, you are a physicist or a chemist and want to measure a rate constant k. You have performed the same kinetic measurement ten times under slightly different conditions. All these measurements have, of course, the same k, but other parameters, like amplitude and time-zero, will differ from experiment to experiment. Now, the usual way would be to perform one fit for each of these ten data sets and average over the resulting k's.
There is a problem with this approach: you don't really know which weight you have to assign to each of the measurements, and how to treat the overlapping error margins of the individual fits. You might want to perform a fit on all your data sets simultaneously, taking the same k for all data sets, and assigning individual amplitudes etc. to each set. This is precisely what the multiLinfit and multiNonlinfit functions of MatrixLib are designed for. You can fit multiple data-sets both to linear and nonlinear models, for Y = f(X) data as well as for MZ = f(X,Y) data.
|
Pascal with DOS only:
The module in which you define your model function must be compiled using the "Force Far Calls" option (Options/Compiler in the IDE or switch {$F+} ) ! |
The multiLinfit and multiNonlinfit functions need the input data to be passed in structures named VF_EXPERIMENT for X-Y data and MF_EXPERIMENT for X-Y-Z data. In C/C++, VF_EXPERIMENT has the following fields:
fVector X, Y; | X and Y vectors: independent variable x and measured y=f(x) data |
fVector InvVar; | inverse variances of the individual data points (needed only for the "with weights" functions) |
ui size; | the number of data points |
float WeightOfExperiment; | individual weight to be assigned to the whole experiment (again needed only for the weighted variants) |
In C/C++, MF_EXPERIMENT has the following fields:
fVector X, Y; | X and Y vectors (independent variables) |
fMatrix Z; | measured data z=f(x,y) |
fMatrix InvVar; | inverse variances of the individual matrix
elements (needed only for the "with weights" functions) |
unsigned htZ, lenZ; | matrix dimensions |
float WeightOfExperiment; | individual weight to be assigned to the whole experiment (again needed only for the weighted variants) |
In Pascal/Delphi, VF_EXPERIMENT and MF_EXPERIMENT are defined as follows:
type VF_EXPERIMENT = record
X, Y, InvVar: fVector;
size: UInt;
WeightOfExperiment: Single;
end;
type PVF_EXPERIMENT = ^VF_EXPERIMENT;
type MF_EXPERIMENT = record
X, Y: fVector;
MZ, MInvVar: fMatrix;
htZ, lenZ: UInt;
WeightOfExperiment: Single;
end;
type PMF_EXPERIMENT = ^MF_EXPERIMENT;
Both in VF_EXPERIMENT and MF_EXPERIMENT, InvVar and WeightOfExperiment are needed only for the weighted variants of the multifit functions.
13.5 Helper Functions for Nonlinear Fits
As nonlinear fitting tasks - especially with multiple data sets - may become quite tedious and take a very long time (sometimes many hours!) to converge, there is a number of functions which allow to follow the course of nonlinear
fits. The names of these functions are always derived from the fitting function they are used with. For example, the helper functions for VF_nonlinfit are:
For the other nonlinear fitting functions, the corresponding helper-function names are obtained by replacing the "VF_nonlinfit_" prefix with the respective fitting function name, as in VF_nonlinfitwW_getBestValues,
MF_multiNonlinfit_stop, and so on.
There are two possibilities how these functions can be called. The first way is to call them from within your model function. For example, you might install a counter into your model function and, upon reaching a certain
number of calls, retrieve the current chi2, parameter set, etc. The second way is open only for multithreaded programs: a thread, different from the one performing the fit, may call any of the above functions to control the progress of the fit.
Back to Table of Contents
14. Matrix Input and Output
The matrix input/output functions are all analogous to the corresponding vector functions
MF_cprint |
print a matrix to the screen. If necessary, rows are cut off at the screen boundaries. If there are more rows than screen lines, proper paging is applied. (DOS and Delphi only) |
MF_print | print a matrix to the screen (without paging or row cut-off); (DOS, EasyWin and Delphi only) |
MF_fprint | print a matrix in ASCII format to a stream |
MF_store | store in binary format |
MF_recall | retrieve in binary format |
MF_write | write in ASCII format in a stream |
MF_read | read from an ASCII file |
Back to Table of Contents
15. Graphical Representation of Matrices
True 3D-plotting functions will be included in future versions. For now, only color-density plots are available. In these plots, each data value is translated into a color value by linear interpolation between two colors, specified as mincolor and maxcolor.
MF_xyzAutoDensityMap | Color density map for z=f(x,y) with automatic scaling of the x and y axes and of the color density scale between mincolor and maxcolor |
MF_xyzDataDensityMap | z=f(x,y) color density map, plotted into an existing axis frame, and using the color density scale set by the last call to an AutoDensityMap function |
MF_zAutoDensityMap | Color density map for z=f(i,j) with automatic scaling of the x and y axes and of the color density scale between mincolor and maxcolor. i and j are the indices in x and y direction, respectively |
MF_zDataDensityMap | Color density map for z=f(i,j), plotted into an existing axis frame, and using the color density scale set by the last call to an AutoDensityMap function |
M_setDensityBounds | Set a color scale for matrix color-density plots. |
M_setDensityMapBounds | Set a color scale and draw an X-Y coordinate system for matrix color-density plots. |
M_findDensityMapBounds | Calculate a color scale and draw an X-Y coordinate system for matrix color-density plots, ensuring that the grid lines of the coordinate system correspond to exact (rather than only rounded) values. |
Back to Table of Contents
16. Alphabetical Reference of MatrixLib
This chapter describes, in alphabetical order, all MatrixLib functions. Similarly to the indexing of the vector functions in FUNCREF.HTM, the MF_ or M_ prefix is neglected in the ordering of entries. The particles "Row_", "Rows_", "Col_", "Cols_", "Dia_", and "Trd_", however, are fully taken into account. For example, "MF_Rows_" functions will come after all "MF_Row_" functions. While most MatrixLib functions have the prefixes MF_ or M_, please note that some - notably the X-Y fitting functions - have the prefix VF_ as a reminder that they actually work on vectors, even if they rely on matrix methods and form a part of MatrixLib. In cases where both the VF_ and the MF_ versions exist, contrary to the alphabetical order the VF_ version is described first, as it is the simpler one.
MFs_addM |
MDs_addM |
MEs_addM |
MCF_addM |
MCD_addM |
MCE_addM |
|
Function | element-wise addition of two matrices |
|
Syntax C/C++ | #include <MFstd.h>
void MF_addM( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len );
void MFs_addM( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::addM( const matrix<T>& MA, const matrix<T>& MB);
void matrix<T>::s_addM( const matrix<T>& MA, const matrix<T>& MB, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_addM( MC, MA, MB:fMatrix C; ht, len:UInt );
procedure MFs_addM( MC, MA, MB:fMatrix C; ht, len:UInt; C:Single ); |
|
Description | normal version: MCij = MAij + MBij
scaled version: MCij = C * (MAij + MBij) |
|
|
MF_addMT
| MD_addMT |
ME_addMT |
MFs_addMT |
MDs_addMT |
MEs_addMT |
MCF_addMT |
MCD_addMT |
MCE_addMT |
|
Function | element-wise addition of one matrix and the transpose of another |
|
Syntax C/C++ | #include <MFstd.h>
void MF_addMT( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len );
void MFs_addMT( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::addMT( const matrix<T>& MA, const matrix<T>& MB);
void matrix<T>::s_addMT( const matrix<T>& MA, const matrix<T>& MB, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_addMT( MC, MA, MB:fMatrix C; ht, len:UInt );
procedure MFs_addMT( MC, MA, MB:fMatrix C; ht, len:UInt; C:Single ); |
|
Description | normal version: MCij = MAij + MBTji
scaled version: MCij = C * (MAij + MBTji) |
|
|
MF_autocorr
| MD_autocorr |
ME_autocorr |
|
Function | Spatial autocorrelation function |
|
Syntax C/C++ | #include <MFstd.h>
void MF_autocorr( fMatrix Y, fMatrix X, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::autocorr( const matrix<T>& MX); |
Pascal/Delphi | uses MFstd;
procedure MF_autocorr( MY, MX:fMatrix; ht, len:UInt ); |
|
Description | The spatial autocorrelation function (SACF) of MX is calculated and stored in MY in wrap-around order in both dimensions: The row elements MYi,0 to MYi,len/2-1 contain the SACF for zero and positive x lags. Beginning with the most negative lag in MYi,len/2+1, the elements up to MYi,len-1 contain the SACF for negative lags. Since this function assumes MX to be periodic, the SACF for the most positive lag is identical to the SACF for the most negative lag. This element is stored as Yi,len/2.
Similarly, the column elements MY0,j to MYlen/2-1,j contain the SACF for zero and positive y lags. Beginning with the most negative lag in MYlen/2+1,j, the elements up to MYlen-1,j contain the SACF for negative lags.
To get the SACF into normal order, you may call
MF_Rows_rotate( MY, ht, len, len/2 );
MF_Cols_rotate( MY, ht, len, ht/2 );
After that, the zero point is at the position MYht/2,len/2.
In case MX is non-periodic, you should avoid end effects by the methods described in connection with MF_convolve.
Both ht and len must be integer powers of 2.
About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM. |
|
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_autocorr is based) complains "Size must be an integer power of 2" and the program is aborted. |
|
|
MF_block_equM
| MD_block_equM |
ME_block_equM |
MCF_block_equM |
MCD_block_equM |
MCE_block_equM |
|
Function | Copy a matrix into a "block" of another matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_block_equM( fMatrix Dest,
unsigned destHt, unsigned destLen,
unsigned firstRow, unsigned firstCol,
fMatrix Srce, unsigned srceHt, unsigned srceLen ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::block_equM( const unsigned firstRow, const unsigned firstCol, const matrix<T>& MSrce); |
Pascal/Delphi | uses MFstd;
procedure MF_block_equM( MDest:fMatrix;
destHt, destLen, firstRow, firstCol:UInt;
MSrce:fMatrix; srceHt, srceLen:UInt ); |
|
Descriptions | MDesti+firstRow, j+firstCol = MSrcei, j, i=0,...,srceHt-1; j=0,...,srceLen-1 |
|
|
MF_block_equMT
| MD_block_equMT |
ME_block_equMT |
MCF_block_equMT |
MCD_block_equMT |
MCE_block_equMT |
|
Function | Copy the transpose of a matrix into a "block" of another matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_block_equMT( fMatrix Dest,
unsigned destHt, unsigned destLen,
unsigned firstRow, unsigned firstCol,
fMatrix Srce, unsigned srceHt, unsigned srceLen ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::block_equMT( const unsigned firstRow, const unsigned firstCol, const matrix<T>& MSrce); |
Pascal/Delphi | uses MFstd;
procedure MF_block_equMT( MDest:fMatrix;
destHt, destLen, firstRow, firstCol:UInt;
MSrce:fMatrix; srceHt, srceLen:UInt ); |
|
Descriptions | MDesti+firstRow, j+firstCol = MSrcej, i, i=0,...,srceLen-1; j=0,...,srceHt-1 |
|
|
|
Function | Data type conversions. See M_FtoD.
|
|
MF_Col_addC
| MD_Col_addC |
ME_Col_addC |
MCF_Col_addC |
MCD_Col_addC |
MCE_Col_addC |
|
Function | add a constant to all elements of one column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_addC( fMatrix A, unsigned ht, unsigned len, unsigned iCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_addC( const unsigned iCol, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_addC( MA:fMatrix; ht, len, iCol:UInt; C:Single ); |
|
Description | MAi,iCol += C, i=0,...,ht-1 |
|
|
MF_Col_addV
| MD_Col_addV |
ME_Col_addV |
MCF_Col_addV |
MCD_Col_addV |
MCE_Col_addV |
|
Function | add a vector to a column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_addV( fMatrix A, unsigned ht, unsigned len, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_addV( const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_addV( MA:fMatrix; ht, len, iCol:UInt; X:fVector ); |
|
Description | MAi,iCol += Xi, i=0,...,ht-1 |
|
|
MF_Col_delete
| MD_Col_delete |
ME_Col_delete |
MCF_Col_delete |
MCD_Col_delete |
MCE_Col_delete |
|
Function | delete one column from a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_delete( fMatrix B, fMatrix A, unsigned htA, unsigned lenA, unsigned iCol ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_delete( const matrix<T>& MA, const unsigned iCol); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_delete( MB, MA:fMatrix; htA, lenA, iCol:UInt ); |
|
Description | MBi,j = MAi,j, i=0,..htA-1, j=0,..iCol-1
MBi,j = MAi,j+1, i=0,...,htA-1, j=iCol,...,lenA-2
The parameters htA and lenA refer to the input matrix |
|
|
MF_Col_divC
| MD_Col_divC |
ME_Col_divC |
MCF_Col_divC |
MCD_Col_divC |
MCE_Col_divC |
|
Function | divide all elements of one column by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_divC( fMatrix A, unsigned ht, unsigned len, unsigned iCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_divC( const unsigned iCol, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_divC( MA:fMatrix; ht, len, iCol:UInt; C:Single ); |
|
Description | MAi,iCol /= C, i=0,...,ht-1 |
|
|
MF_Col_divrC
| MD_Col_divrC |
ME_Col_divrC |
MCF_Col_divrC |
MCD_Col_divrC |
MCE_Col_divrC |
|
Function | Reverse division: divide a constant by a column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_divrC( fMatrix A, unsigned ht, unsigned len, unsigned iCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_divrC( const unsigned iCol, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_divrC( MA:fMatrix; ht, len, iCol:UInt; C:Single ); |
|
Description | MAi,iCol = C / MAi,iCol, i=0,...,ht-1 |
|
|
MF_Col_divrV
| MD_Col_divrV |
ME_Col_divrV |
MCF_Col_divrV |
MCD_Col_divrV |
MCE_Col_divrV |
|
Function | Reverse division: divide a vector by a column (element-wise) |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_divrV( fMatrix A, unsigned ht, unsigned len, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_divrV( const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_divrV( MA:fMatrix; ht, len, iCol:UInt; X:fVector ); |
|
Description | MAi,iCol = Xi / MAi,iCol, i=0,...,ht-1 |
|
|
MF_Col_divV
| MD_Col_divV |
ME_Col_divV |
MCF_Col_divV |
MCD_Col_divV |
MCE_Col_divV |
|
Function | element-wise division of a column by a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_divV( fMatrix A, unsigned ht, unsigned len, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_divV( const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_divV( MA:fMatrix; ht, len, iCol:UInt; X:fVector ); |
|
Description | MAi,iCol /= Xi, i=0,...,ht-1 |
|
|
MF_Col_equ0
| MD_Col_equ0 |
ME_Col_equ0 |
MCF_Col_equ0 |
MCD_Col_equ0 |
MCE_Col_equ0 |
|
Function | set all elements of one column to zero |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_equ0( fMatrix A, unsigned ht, unsigned len, unsigned iCol ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_equ0( const unsigned iCol ); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_equ0( MA:fMatrix; ht, len, iCol:UInt ); |
|
Description | MAi,iCol = 0, i=0,...,ht-1 |
|
|
MF_Col_equC
| MD_Col_equC |
ME_Col_equC |
MCF_Col_equC |
MCD_Col_equC |
MCE_Col_equC |
|
Function | initialize all elements of one column with a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_equC( fMatrix A, unsigned ht, unsigned len, unsigned iCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_equC( const unsigned iCol, const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_equC( MA:fMatrix; ht, len, iCol:UInt; C:Single ); |
|
Description | MAi,iCol = C, i=0,...,ht-1 |
|
|
MF_Col_equV
| MD_Col_equV |
ME_Col_equV |
MCF_Col_equV |
MCD_Col_equV |
MCE_Col_equV |
|
Function | copy a vector into one column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_equV( fMatrix A, unsigned ht, unsigned len, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_equV( const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_equV( MA:fMatrix; ht, len, iCol:UInt; X:fVector ); |
|
Description | MAi,iCol = Xi, i=0,...,ht-1 |
|
|
MF_Col_extract
| MD_Col_extract |
ME_Col_extract |
MCF_Col_extract |
MCD_Col_extract |
MCE_Col_extract |
|
Function | copy one column into a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_extract( fVector Y, fMatrix A, unsigned ht, unsigned len, unsigned iCol ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Col_extract( const matrix<T>& MA, const unsigned iCol ); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_extract( Y:fVector; MA:fMatrix; ht, len, iCol:UInt ); |
|
Description | Yi = MAi,iCol, i=0,...,ht-1 |
|
|
MF_Col_insert
| MD_Col_insert |
ME_Col_insert |
MCF_Col_insert |
MCD_Col_insert |
MCE_Col_insert |
|
Function | augment a matrix by insertion of one column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_insert( fMatrix B, fMatrix A, unsigned htB, unsigned lenB, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_insert( const matrix<T>& MA, const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_insert( MB, MA:fMatrix; htB, lenB, iCol:UInt; X:fVector ); |
|
Description | MBi,j = MAi,j, i=0,...,htB-1, j=0,...,iCol-1
MBi,iCol = Xi, i=0,...,htB-1
MBi,j = MAi,j-1, i=0,...,htB-1, j=iCol,...,lenB-1
The parameters htB and lenB refer to the output matrix |
|
|
MF_Col_mulC
| MD_Col_mulC |
ME_Col_mulC |
MCF_Col_mulC |
MCD_Col_mulC |
MCE_Col_mulC |
|
Function | multiply all elements of one column by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_mulC( fMatrix A, unsigned ht, unsigned len, unsigned iCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_mulC( const unsigned iCol, const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_mulC( MA:fMatrix; ht, len, iCol:UInt; C:Single ); |
|
Description | MAi,iCol *= C, i=0,...,ht-1 |
|
|
MF_Col_mulV
| MD_Col_mulV |
ME_Col_mulV |
MCF_Col_mulV |
MCD_Col_mulV |
MCE_Col_mulV |
|
Function | element-wise multiplication of a column by a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_mulV( fMatrix A, unsigned ht, unsigned len, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_mulV( const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_mulV( MA:fMatrix; ht, len, iCol:UInt; X:fVector ); |
|
Description | MAi,iCol *= Xi, i=0,..,ht-1 |
|
|
MF_Col_subC
| MD_Col_subC |
ME_Col_subC |
MCF_Col_subC |
MCD_Col_subC |
MCE_Col_subC |
|
Function | subtract a constant from all elements of one column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_subC( fMatrix A, unsigned ht, unsigned len, unsigned iCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_subC( const unsigned iCol, const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_subC( MA:fMatrix; ht, len, iCol:UInt; C:Single ); |
|
Description | MAi,iCol -= C, i=0,..,ht-1 |
|
|
MF_Col_subrC
| MD_Col_subrC |
ME_Col_subrC |
MCF_Col_subrC |
MCD_Col_subrC |
MCE_Col_subrC |
|
Function | reverse subtraction: a constant minus one column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_subrC( fMatrix A, unsigned ht, unsigned len, unsigned iCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_subrC( const unsigned iCol, const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_subrC( MA:fMatrix; ht, len, iCol:UInt; C:Single ); |
|
Description | MAi,iCol = C - MAi,iCol, i=0,..,ht-1 |
|
|
MF_Col_subrV
| MD_Col_subrV |
ME_Col_subrV |
MCF_Col_subrV |
MCD_Col_subrV |
MCE_Col_subrV |
|
Function | reverse subtraction: a vector minus one column (element-wise) |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_subrV( fMatrix A, unsigned ht, unsigned len, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_subrV( const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_subrV( MA:fMatrix; ht, len, iCol:UInt; X:fVector ); |
|
Description | MAi,iCol = Xi - MAi,iCol, i=0,..,ht-1 |
|
|
MF_Col_subV
| MD_Col_subV |
ME_Col_subV |
MCF_Col_subV |
MCD_Col_subV |
MCE_Col_subV |
|
Function | subtract a vector from a column (element-wise) |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Col_subV( fMatrix A, unsigned ht, unsigned len, unsigned iCol, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Col_subV( const unsigned iCol, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Col_subV( MA:fMatrix; ht, len, iCol:UInt; X:fVector ); |
|
Description | MAi,iCol -= Xi, i=0,..,ht-1 |
|
|
MF_Cols_absmax
| MD_Cols_absmax |
ME_Cols_absmax |
MCF_Cols_absmax |
MCD_Cols_absmax |
MCE_Cols_absmax |
|
Function | store the absolute maxima of all individual columns in a row vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_absmax( fVector Y, fMatrix A, unsigned ht, unsigned len );
void MCF_Cols_absmax( fVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Cols_absmax( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_absmax( Y:fVector; MA:fMatrix; ht, len:UInt );
procedure MCF_Cols_absmax( Y:fVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The maximum absolute value of each column j is stored as the element Yj for j=0,..,len-1 |
|
|
MCF_Cols_absmaxReIm
| MCD_Cols_absmaxReIm |
MCE_Cols_absmaxReIm |
|
Function | Separate determination of the largest absolute values of the real and imaginary parts of each column |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Cols_absmaxReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Cols_absmaxReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Cols_absmaxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The maximum absolute values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1 |
|
|
MF_Cols_absmin
| MD_Cols_absmin |
ME_Cols_absmin |
MCF_Cols_absmin |
MCD_Cols_absmin |
MCE_Cols_absmin |
|
Function | store the absolute minima of all individual columns in a row vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_absmin( fVector Y, fMatrix A, unsigned ht, unsigned len );
void MCF_Cols_absmin( fVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Cols_absmin( const matrix<T>& MA );
void vector<T>::Cols_absmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_absmin( Y:fVector; MA:fMatrix; ht, len:UInt );
procedure MCF_Cols_absmin( Y:fVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The minimum absolute value of each column j is stored as the element Yj for j=0,..,len-1 |
|
|
MCF_Cols_absminReIm
| MCD_Cols_absminReIm |
MCE_Cols_absminReIm |
|
Function | Separate determination of the smallest absolute values of the real and imaginary parts of each column |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Cols_absminReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Cols_absminReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Cols_absminReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The minimum absolute values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1 |
|
|
MF_Cols_add
| MD_Cols_add |
ME_Cols_add |
MCF_Cols_add |
MCD_Cols_add |
MCE_Cols_add |
|
Function | make one column the sum of itself and another column |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_add( fMatrix A, unsigned ht, unsigned len, unsigned destCol, unsigned sourceCol ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_add( const unsigned destCol, const unsigned sourceCol ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_add( MA:fMatrix; ht, len, destCol, sourceCol:UInt ); |
|
Description | MAi,destCol += MAi,sourceCol, i=0,..,ht-1 |
|
|
MCF_Cols_cabsmax
| MCD_Cols_cabsmax |
MCE_Cols_cabsmax |
|
Function | Find the complex numbers of largest magnitude along columns and store them in a row vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Cols_cabsmax( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Cols_cabsmax( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Cols_cabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each column j of MA, the complex number of largest magnitude, sqrt(Re2+Im2), is found and stored as the element Yj for j=0,..,len-1 |
|
|
MCF_Cols_cabsmin
| MCD_Cols_cabsmin |
MCE_Cols_cabsmin |
|
Function | Find the complex numbers of smallest magnitude along columns and store them in a row vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Cols_cabsmin( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Cols_cabsmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Cols_cabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each column j of MA, the complex number of smallest magnitude, sqrt(Re2+Im2), is found and stored as the element Yj for j=0,..,len-1 |
|
|
MF_Cols_Cadd
| MD_Cols_Cadd |
ME_Cols_Cadd |
MCF_Cols_Cadd |
MCD_Cols_Cadd |
MCE_Cols_Cadd |
|
Function | make one column the sum of itself and another column, scaled by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_Cadd( fMatrix A, unsigned ht, unsigned len, unsigned destCol, unsigned sourceCol, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_Cadd( const unsigned destCol, const unsigned sourceCol, const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_Cadd( MA:fMatrix; ht, len, destCol, sourceCol:UInt;
C:Single ); |
|
Description | MAi,destCol += C * MAi,sourceCol, i=0,..,ht-1 |
|
|
MF_Cols_exchange
| MD_Cols_exchange |
ME_Cols_exchange |
MCF_Cols_exchange |
MCD_Cols_exchange |
MCE_Cols_exchange |
|
Function | exchange two columns |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_exchange( fMatrix A, unsigned ht, unsigned len, unsigned i1, unsigned i2 ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_exchange( const unsigned i1, const unsigned i2 ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_exchange( MA:fMatrix; ht, len, i1, i2:UInt ); |
|
Description | The elements of the columns i1 and i2 are exchanged. |
|
|
MF_Cols_lincomb
| MD_Cols_lincomb |
ME_Cols_lincomb |
MCF_Cols_lincomb |
MCD_Cols_lincomb |
MCE_Cols_lincomb |
|
Function | linear combination of two columns |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_lincomb( fMatrix A, unsigned ht, unsigned len, unsigned destCol, float destC, unsigned srceCol, float srceC ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_lincomb( const unsigned destCol, const T& destC, const unsigned srceCol, const T& srceC ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_lincomb( MA:fMatrix; ht, len:UInt; destCol:UInt; destC:Single; srceCol:Uint; srceC:Single ); |
|
Description | MAi,destCol = destC * MAi,destCol+ srceC * MAi,srceCol, i=0,..,ht-1 |
|
|
MF_Cols_max
| MD_Cols_max |
ME_Cols_max |
MCF_Cols_max |
MCD_Cols_max |
MCE_Cols_max |
|
Function | store the maxima of all individual columns in a row vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_max( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Cols_max( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_max( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | The maximum value of each column j is stored as the element Yj for j=0,..,len-1 |
|
|
MCF_Cols_maxReIm
| MCD_Cols_maxReIm |
MCE_Cols_maxReIm |
|
Function | Separate determination of the largest values of the real and imaginary parts of each column |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Cols_maxReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Cols_maxReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Cols_maxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The maximum values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1 |
|
|
MF_Cols_min
| MD_Cols_min |
ME_Cols_min |
MCF_Cols_min |
MCD_Cols_min |
MCE_Cols_min |
|
Function | store the minima of all individual columns in a row vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_min( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Cols_min( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_min( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | The minimum value of each column j is stored as the element Yj for j=0,..,len-1 |
|
|
MCF_Cols_minReIm
| MCD_Cols_maxReIm |
MCE_Cols_maxReIm |
|
Function | Separate determination of the largest values of the real and imaginary parts of each column |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Cols_maxReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Cols_minReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Cols_minReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The maximum values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1 |
|
|
MF_Cols_prod
| MD_Cols_prod |
ME_Cols_prod |
MCF_Cols_prod |
MCD_Cols_prod |
MCE_Cols_prod |
|
Function | products over all elements of each individual column, stored in a row vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_prod(fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Cols_prod( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_prod(Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | Yj = prod( MAi,j, i=0,..,ht-1), j=0,..,len-1 |
|
|
MF_Cols_reflect
| MD_Cols_reflect |
ME_Cols_reflect |
|
Function | Derive the second halves of all columns from their first halves by reflection at the horizontal line through the center of the matrix. |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_reflect( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_reflect(); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_reflect( MA:fMatrix; ht, len:UInt ); |
|
Description | MAht-i-1,j = MAi, j, i=0,..(ht-1)/2; j=0,..,len-1 |
|
|
MF_Cols_rotate
| MD_Cols_rotate |
ME_Cols_rotate |
MCF_Cols_rotate |
MCD_Cols_rotate |
MCE_Cols_rotate |
|
Function | rotate all columns by a specified number of positions; thereby, whole rows are moved |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_rotate( fMatrix A, unsigned ht, unsigned len, int pos ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_rotate( const int pos ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_rotate( MA:fMatrix; ht, len:UInt; pos:Integer ); |
|
Description | MAi,j = MAht-pos+i, j, i=0,..,pos-1
MAi,j = MAi-pos, j, i=pos,...,ht-1
|
|
|
MF_Cols_runprod
| MD_Cols_runprod |
ME_Cols_runprod |
MCF_Cols_runprod |
MCD_Cols_runprod |
MCE_Cols_runprod |
|
Function | running product over column elements |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_runprod( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_runprod(); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_runprod( MA:fMatrix; ht, len:UInt ); |
|
Description | For all columns separately, each element is the product of itself and all preceding elements. This function should be used with care: overflow is easily reached, and underflow may lead to all elements from a certain position on being zero. |
|
|
MF_Cols_runsum
| MD_Cols_runsum |
ME_Cols_runsum |
MCF_Cols_runsum |
MCD_Cols_runsum |
MCE_Cols_runsum |
|
Function | running sum over column elements |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_runsum( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_runsum(); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_runsum( MA:fMatrix; ht, len:UInt ); |
|
Description | For all columns separately, each element is the sum of itself and all preceding elements. |
|
|
MCF_Cols_sabsmax
| MCD_Cols_sabsmax |
MCE_Cols_sabsmax |
|
Function | Find the complex numbers of largest sum |Re| + |Im| along columns and store them in a row vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Cols_sabsmax( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Cols_sabsmax( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Cols_sabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each column j of MA, the complex number with the largest sum, |Re| + |Im|, is found and stored as the element Yj for j=0,..,len-1 |
|
|
MCF_Cols_sabsmin
| MCD_Cols_sabsmin |
MCE_Cols_sabsmin |
|
Function | Find the complex numbers of largest sum |Re| + |Im| along columns and store them in a row vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Cols_sabsmin( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Cols_sabsmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Cols_sabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each column j of MA, the complex number with the largest sum, |Re| + |Im|, is found and stored as the element Yj for j=0,..,len-1 |
|
|
MF_Cols_sub
| MD_Cols_sub |
ME_Cols_sub |
MCF_Cols_sub |
MCD_Cols_sub |
MCE_Cols_sub |
|
Function | subtract one column from another and store the result back into the subtrahend |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_sub( fMatrix A, unsigned ht, unsigned len, unsigned destCol, unsigned sourceCol ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Cols_sub( const unsigned destCol, const unsigned sourceCol ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_sub( MA:fMatrix; ht, len, destCol, sourceCol:UInt; ); |
|
Description | MAi,destCol -= MAi,sourceCol, i=0,..,ht-1 |
|
|
MF_Cols_sum
| MD_Cols_sum |
ME_Cols_sum |
MCF_Cols_sum |
MCD_Cols_sum |
MCE_Cols_sum |
|
Function | sums over all columns, returned in a row vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Cols_sum( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Cols_sum( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Cols_sum( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | Yj = sum( MAi,j, i=0,..,ht-1), j=0,..,len-1 |
|
|
MCF_conj
| MCD_conj |
MCE_conj |
|
Function | complex conjugate |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_conj( cfMatrix B, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::conj(); |
Pascal/Delphi | uses MFstd;
procedure MCF_conj( MB, MA:cfMatrix; ht, len:UInt ); |
|
Description | MBij.Re = MAij.Re
MBij.Im = -MAij.Im |
|
|
MF_convolve
| MD_convolve |
ME_convolve |
|
Function | convolution with a spatial response function |
|
Syntax C/C++ | #include <MFstd.h>
void MF_convolve( fMatrix Y, fMatrix Flt, fMatrix X, fMatrix Rsp, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::convolve( matrix<T> Flt, const matrix<T>& MX, const matrix<T> Rsp);
void matrix<T>::convolve( matrix<T>* Flt, const matrix<T>& MX, const matrix<T> Rsp); |
Pascal/Delphi | uses MFstd;
procedure MF_convolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UInt ); |
|
Description | The convolution of MX with the response function MRsp is calculated and stored in MY. A filter MFlt is also calculated. If more than one matrix is to be convolved with the same MRsp, use MF_convolve only once and use MF_filter for the other matrices.
The response has to be stored in MRsp in wrap-around order in both dimensions: in each row i of MRsp, the response for zero and positive x-values is stored in MRspi,0 to MRspi,len/2 and the response for negative x-values (beginning with the most negative x) in MRspi,len/2+1 to MRspi,len-1.
Similarly, in each column of MRsp, the response for zero and positive y-values is stored in MRsp0,j to MRsplen/2,j and the response for negative y-values (beginning with the most negative y) in MRsplen/2+1,j to MRsplen-1,j.
You may wish to use MF_Rows_rotate and MF_Cols_rotate, or MF_Rows_reflect and MF_Cols_reflect to achieve this wrap-around order and to construct the response matrix. The result of the convolution appears scaled with the sum of all elements of MRsp. Normally, therefore, MRsp should be normalized to 1.0.
MX, MY, MRsp, and MFlt must all be of the same dimensions. Both len and ht have to be integer powers of 2. MX may be overwritten by MY, MRsp may be overwritten by MFlt, but MX and MFlt as well as MY and MRsp have to be distinct from each other.
As in the one-dimensional case, the treatment of round-off errors in the construction of MFlt may be modified by VF_setRspEdit.
The input matrix is assumed to be periodic in both dimensions. See the description of VF_convolve on how to avoid end effects, in case it is not periodic.
About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM. |
|
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_convolve is based) complains "Size must be an integer power of 2" and the program is aborted. |
|
|
MF_cprint
| MD_cprint |
ME_cprint |
MCF_cprint |
MCD_cprint |
MCE_cprint |
|
Function | print a matrix to the screen (DOS and Win32-console only; not for Visual C++) |
|
Syntax C/C++ | #include <MFstd.h>
void MF_cprint( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::cprint(); |
Pascal/Delphi | uses MFstd;
procedure MF_cprint( MA:fMatrix; ht, len:UInt ); |
|
Description | The matrix MA is printed to the screen. Each line corresponds to one row of the matrix. The lines are numbered. If necessary, rows are cut off at the screen boundaries. If there are more rows than screen lines, proper paging is applied.
This family of functions is available only for DOS and Win32 console applications with the Borland compilers. It should not be used within TurboVision DOS programs. |
|
Error handling | If the number of columns exceeds the maximum number of entries possible in the current text mode, an error message "Cannot use requested format (too many entries per line)!" is generated; in this case, the rows are truncated. |
|
|
MF_deconvolve
| MD_deconvolve |
ME_deconvolve |
|
Function | spatial deconvolution, edge sharpening |
|
Syntax C/C++ | #include <MFstd.h>
void MF_deconvolve( fMatrix Y, fMatrix Flt, fMatrix X, fMatrix Rsp, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::deconvolve( matrix<T> Flt, const matrix<T>& MX, const matrix<T> Rsp);
void matrix<T>::deconvolve( matrix<T>* Flt, const matrix<T>& MX, const matrix<T> Rsp); |
Pascal/Delphi | uses MFstd;
procedure MF_deconvolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UInt ); |
|
Description | MX is assumed to be the result of a convolution of some "true" profile with the response function MRsp; a deconvolution is attempted and stored in MY. A filter MFlt is also calculated; if more than one matrix is to be deconvolved with the same MRsp, use MF_deconvolve only once and use the filter MFlt thus obtained to deconvolve other matrices by calling MF_filter. The response has to be stored in the wrap-around order described above for MF_convolve.
As for MF_convolve, MX, MY, MRsp, and MFlt must all be of the same dimensions, which have to be integer powers of 2. MX may be overwritten by MY, MRsp may be overwritten by MFlt, but MX and MFlt as well as MY and MRsp have to be distinct from each other.
Mathematically, MFlt is the inverse of the Fourier transform of MRsp. If the Fourier transform of MRsp contains elements equal to zero, all information is lost for the respective frequency and no reconstruction is possible. The best one can do in this case is to accept this loss and to deconvolve only up to those frequencies where still something is left to be reconstructed.
You are therefore advised not to use this function blindly but rather to inspect the Fourier transform of MRsp and decide what to do on the basis of your specific application. If you wish to use this function nevertheless, you may rely on the automatic editing of the filter, built into MF_deconvolve. Thereby, MFlt is set to zero (instead of infinity) at those frequences where all information has been lost. You may set the threshold for this implicit editing by VF_setRspEdit. In order to retrieve the threshold actually set, use VF_getRspEdit. (These two functions are shared between the one- and two-dimensional FFT functions and described in FUNCREF.HTM.)
This deconvolution is based on the implicit assumption that MX is periodic; if this is not the case, see the description of VF_convolve about how to avoid end effects. |
|
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_deconvolve is based) complains "Size must be an integer power of 2" and the program is aborted.
If, by VF_setRspEdit, you specified Trunc.Re = Trunc.Im = 0, SING errors may occur that are handled by setting MFlt to ±HUGE_VAL at the respective frequency. During multiplication with the transform of MX, this may lead to unhandled floating-point overflow errors (in case your guess of MRsp was wrong and there is some information left at the frequencies where you thought it was not).
About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM. |
|
|
|
Function | determinant of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_det( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::det(); |
Pascal/Delphi | uses MFstd;
function MF_det( MA:fMatrix; len:UInt ):Single; |
|
Description | The determinant of MA is calculated. For large matrices, this is done via LU decomposition. For small matrices, individual formulae are applied. |
|
Return value | determinant of the matrix |
|
|
MF_Dia_absmax
| MD_Dia_absmax |
ME_Dia_absmax |
MCF_Dia_absmax |
MCD_Dia_absmax |
MCE_Dia_absmax |
|
Function | absolute maximum of the elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_Dia_absmax( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::Dia_absmax(); |
Pascal/Delphi | uses MFstd;
function MF_Dia_absmax( MA:fMatrix; len:UInt ):Single; |
|
Description | The maximum absolute value of all elements MAi,i is returned as a scalar |
|
Return value | absolute maximum of the diagonal |
|
|
MCF_Dia_absmaxReIm
| MCD_Dia_absmaxReIm |
MCE_Dia_absmaxReIm |
|
Function | Separate determination of the largest absolute values of the real and imaginary parts occurring along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_absmaxReIm( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_absmaxReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_absmaxReIm( var Max:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The maximum absolute values of the real and imaginary parts of the diagonal of a square matrix are combined into the complex return value (or, for Pascal/Delphi, into the variable Max). |
|
|
MF_Dia_absmin
| MD_Dia_absmin |
ME_Dia_absmin |
MCF_Dia_absmin |
MCD_Dia_absmin |
MCE_Dia_absmin |
|
Function | absolute minimum of the elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_Dia_absmin( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::Dia_absmin(); |
Pascal/Delphi | uses MFstd;
function MF_Dia_absmin( MA:fMatrix; len:UInt ):Single; |
|
Description | The minimum absolute value of all elements MAi,i is returned as a scalar |
|
Return value | absolute minimum of the diagonal |
|
|
MCF_Dia_absminReIm
| MCD_Dia_absminReIm |
MCE_Dia_absminReIm |
|
Function | Separate determination of the smallest absolute values of the real and imaginary parts occurring along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_absminReIm( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_absminReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_absminReIm( var Min:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The minimum absolute values of the real and imaginary parts of the diagonal of a square matrix are combined into the the complex return value (or, for Pascal/Delphi, into the variable Min). |
|
|
MF_Dia_addC
| MD_Dia_addC |
ME_Dia_addC |
MCF_Dia_addC |
MCD_Dia_addC |
MCE_Dia_addC |
|
Function | add a constant to all elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_addC( fMatrix A, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_addC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_addC( MA:fMatrix; len:UInt; C:Single ); |
|
Description | MAi,i += C, i=0,...,len-1 |
|
|
MF_Dia_addV
| MD_Dia_addV |
ME_Dia_addV |
MCF_Dia_addV |
MCD_Dia_addV |
MCE_Dia_addV |
|
Function | element-wise addition of a vector to the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_addV( fMatrix A, unsigned len, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_addV( const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_addV( MA:fMatrix; len:UInt; X:fVector ); |
|
Description | MAi,i += Xi, i=0,...,len-1 |
|
|
MCF_Dia_cabsmax
| MCD_Dia_cabsmax |
MCE_Dia_cabsmax |
|
Function | Find the complex number of largest magnitude along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_cabsmax( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_cabsmax( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_cabsmax( var Max:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The complex number of largest magnitude, sqrt(Re2+Im2), is found. |
|
|
MCF_Dia_cabsmin
| MCD_Dia_cabsmin |
MCE_Dia_cabsmin |
|
Function | Find the complex number of smallest magnitude along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_cabsmin( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_cabsmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_cabsmin( var Max:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The complex number of smallest magnitude, sqrt(Re2+Im2), is found. |
|
|
MF_Dia_divC
| MD_Dia_divC |
ME_Dia_divC |
MCF_Dia_divC |
MCD_Dia_divC |
MCE_Dia_divC |
|
Function | divide all elements of the diagonal of a square matrix by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_divC( fMatrix A, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_divC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_divC( MA:fMatrix; len:UInt; C:Single ); |
|
Description | MAi,i /= C, i=0,...,len-1 |
|
|
MF_Dia_divrC
| MD_Dia_divrC |
ME_Dia_divrC |
MCF_Dia_divrC |
MCD_Dia_divrC |
MCE_Dia_divrC |
|
Function | reverse division: divide a constant by the elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_divrC( fMatrix A, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_divrC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_divrC( MA:fMatrix; len:UInt; C:Single ); |
|
Description | MAi,i = C / MAi,i, i=0,...,len-1 |
|
|
MF_Dia_divrV
| MD_Dia_divrV |
ME_Dia_divrV |
MCF_Dia_divrV |
MCD_Dia_divrV |
MCE_Dia_divrV |
|
Function | reverse division: divide a vector by the diagonal of a square matrix, storing the result back into the diagonal |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_divrV( fMatrix A, unsigned len, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_divrV( const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_divrV( MA:fMatrix; len:UInt; X:fVector ); |
|
Description | MAi,i = Xi / MAi,i, i=0,...,len-1 |
|
|
MF_Dia_divV
| MD_Dia_divV |
ME_Dia_divV |
MCF_Dia_divV |
MCD_Dia_divV |
MCE_Dia_divV |
|
Function | element-wise division of the diagonal of a square matrix by a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_divV( fMatrix A, unsigned len, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_divV( const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_divV( MA:fMatrix; len:UInt; X:fVector ); |
|
Description | MAi,i / Xi, i=0,...,len-1 |
|
|
MF_Dia_equ0
| MD_Dia_equ0 |
ME_Dia_equ0 |
MCF_Dia_equ0 |
MCD_Dia_equ0 |
MCE_Dia_equ0 |
|
Function | initialize all elements of the diagonal of a square matrix with zero |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_equ0( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_equ0( ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_equ0( MA:fMatrix; len:UInt ); |
|
Description | MAi,i = 0, i=0,...,len-1 |
|
|
MF_Dia_equC
| MD_Dia_equC |
ME_Dia_equC |
MCF_Dia_equC |
MCD_Dia_equC |
MCE_Dia_equC |
|
Function | initialize all elements of the diagonal of a square matrix with a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_equC( fMatrix A, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_equC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_equC( MA:fMatrix; len:UInt; C:Single ); |
|
Description | MAi,i = C, i=0,...,len-1 |
|
|
MF_Dia_equV
| MD_Dia_equV |
ME_Dia_equV |
MCF_Dia_equV |
MCD_Dia_equV |
MCE_Dia_equV |
|
Function | copy a vector into the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_equV( fMatrix A, unsigned len, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_equV( const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_equV( MA:fMatrix; len:UInt; X:fVector ); |
|
Description | MAi,i = Xi, i=0,...,len-1 |
|
|
MF_Dia_extract
| MD_Dia_extract |
ME_Dia_extract |
MCF_Dia_extract |
MCD_Dia_extract |
MCE_Dia_extract |
|
Function | copy the diagonal of a square matrix into a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_extract( fVector Y, fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Dia_extract( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_extract( Y:fVector; MA:fMatrix; len:UInt ); |
|
Description | Yi = MAi,i, i=0,...,len-1 |
|
|
MF_Dia_max
| MD_Dia_max |
ME_Dia_max |
MCF_Dia_max |
MCD_Dia_max |
MCE_Dia_max |
|
Function | maximum of all elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_Dia_max( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::Dia_max(); |
Pascal/Delphi | uses MFstd;
function MF_Dia_max( MA:fMatrix; len:UInt ):Single; |
|
Description | the largest element of the diagonal is returned as a scalar |
|
Return value | maximum of the diagonal |
|
|
MCF_Dia_maxReIm
| MCD_Dia_maxReIm |
MCE_Dia_maxReIm |
|
Function | Separate determination of the largest values of the real and imaginary parts occurring along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_maxReIm( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_maxReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_maxReIm( var Max:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The maximum values of the real and imaginary parts of the diagonal of a square matrix are combined into the complex return value (or, for Pascal/Delphi, into the variable Max). |
|
|
MF_Dia_min
| MD_Dia_min |
ME_Dia_min |
MCF_Dia_min |
MCD_Dia_min |
MCE_Dia_min |
|
Function | minimum of all elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_Dia_min( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::Dia_min(); |
Pascal/Delphi | uses MFstd;
function MF_Dia_min( MA:fMatrix; len:UInt ):Single; |
|
Description | the smallest or most negative element of the diagonal is returned as a scalar |
|
Return value | minimum of the diagonal |
|
|
MCF_Dia_minReIm
| MCD_Dia_minReIm |
MCE_Dia_minReIm |
|
Function | Separate determination of the smallest absolute values of the real and imaginary parts occurring along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_minReIm( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_minReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_minReIm( var Min:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The minimum absolute values of the real and imaginary parts of the diagonal of a square matrix are combined into the the complex return value (or, for Pascal/Delphi, into the variable Min). |
|
|
MF_Dia_mulC
| MD_Dia_mulC |
ME_Dia_mulC |
MCF_Dia_mulC |
MCD_Dia_mulC |
MCE_Dia_mulC |
|
Function | multiply all elements of the diagonal of a square matrix by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_mulC( fMatrix A, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_mulC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_mulC( MA:fMatrix; len:UInt; C:Single ); |
|
Description | MAi,i *= C, i=0,...,len-1 |
|
|
MF_Dia_mulV
| MD_Dia_mulV |
ME_Dia_mulV |
MCF_Dia_mulV |
MCD_Dia_mulV |
MCE_Dia_mulV |
|
Function | element-wise multiplication of the diagonal of a square matrix by a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_mulV( fMatrix A, unsigned len, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_mulV( const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_mulV( MA:fMatrix; len:UInt; X:fVector ); |
|
Description | MAi,i *= Xi, i=0,...,len-1 |
|
|
MF_Dia_prod
| MD_Dia_prod |
ME_Dia_prod |
MCF_Dia_prod |
MCD_Dia_prod |
MCE_Dia_prod |
|
Function | product of all elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_Dia_prod( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::Dia_prod(); |
Pascal/Delphi | uses MFstd;
function MF_Dia_prod( MA:fMatrix; len:UInt ):Single; |
|
Description | the product of the diagonal elements is returned as a scalar |
|
Return value | product of the diagonal elements |
|
|
MCF_Dia_sabsmax
| MCD_Dia_sabsmax |
MCE_Dia_sabsmax |
|
Function | Find the complex number of largest sum |Re| + |Im| along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_sabsmax( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_sabsmax( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_sabsmax( var Max:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The complex number of largest sum |Re| + |Im|, is found. |
|
|
MCF_Dia_sabsmin
| MCD_Dia_sabsmin |
MCE_Dia_sabsmin |
|
Function | Find the complex number of smallest sum |Re| + |Im| along the diagonal of a square matrix |
|
Syntax C/C++ | #include <MCFstd.h>
fComplex MCF_Dia_sabsmin( cfMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
complex<T> matrix<complex<T>>::Dia_sabsmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Dia_sabsmin( var Max:fComplex; MA:cfMatrix; len:UInt ); |
|
Description | The complex number with the smallest sum |Re| + |Im| is found. |
|
|
MF_Dia_subC
| MD_Dia_subC |
ME_Dia_subC |
MCF_Dia_subC |
MCD_Dia_subC |
MCE_Dia_subC |
|
Function | subtract a constant from all elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_subC( fMatrix A, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_subC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_subC( MA:fMatrix; len:UInt; C:Single ); |
|
Description | MAi,i -= C, i=0,...,len-1 |
|
|
MF_Dia_subrC
| MD_Dia_subrC |
ME_Dia_subrC |
MCF_Dia_subrC |
MCD_Dia_subrC |
MCE_Dia_subrC |
|
Function | reverse subtraction: a constant minus the elements of the diagonal of a square matrix, storing the result back into the diagonal |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_subrC( fMatrix A, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_subrC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_subrC( MA:fMatrix; len:UInt; C:Single ); |
|
Description | MAi,i = C - MAi,i, i=0,...,len-1 |
|
|
MF_Dia_subrV
| MD_Dia_subrV |
ME_Dia_subrV |
MCF_Dia_subrV |
MCD_Dia_subrV |
MCE_Dia_subrV |
|
Function | reverse subtraction: subtract the elements of the diagonal of a square matrix from corresponding elements of a vector, storing the result back into the diagonal |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_subrV( fMatrix A, unsigned len, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_subrV( const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_subrV( MA:fMatrix; len:UInt; X:fVector ); |
|
Description | MAi,i = Xi - MAi,i, i=0,...,len-1 |
|
|
MF_Dia_subV
| MD_Dia_subV |
ME_Dia_subV |
MCF_Dia_subV |
MCD_Dia_subV |
MCE_Dia_subV |
|
Function | element-wise subtraction of a vector from the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Dia_subV( fMatrix A, unsigned len, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Dia_subV( const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Dia_subV( MA:fMatrix; len:UInt; X:fVector ); |
|
Description | MAi,i -= Xi, i=0,...,len-1 |
|
|
MF_Dia_sum
| MD_Dia_sum |
ME_Dia_sum |
MCF_Dia_sum |
MCD_Dia_sum |
MCE_Dia_sum |
|
Function | sum over all elements of the diagonal of a square matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_Dia_sum( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::Dia_sum(); |
Pascal/Delphi | uses MFstd;
function MF_Dia_sum( MA:fMatrix; len:UInt ):Single; |
|
Description | the elements of the diagonal are summed up and returned as a scalar |
|
Return value | sum over the diagonal elements |
|
|
MCF_divC |
MCD_divC |
MCE_divC |
MCF_divReC |
MCD_divReC |
MCE_divReC |
|
Function | divide all matrix elements by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_divC( fMatrix B, fMatrix A, unsigned ht, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::divC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_divC( MB, MA:fMatrix; ht, len:UInt; C:Single ); |
|
Description | Mi,j /= C, i=0,...,ht-1; j=0,..,len-1 |
|
|
|
Function | Data type conversions. See M_FtoD. |
|
MF_element
| MD_element |
ME_element |
MCF_element |
MCD_element |
MCE_element |
|
Function | read-only access to a matrix element |
|
Syntax C/C++ | #include <MFstd.h>
float MF_element( fMatrix X, unsigned ht, unsigned len, unsigned m, unsigned n );
fComplex MCF_element( cfMatrix X, unsigned ht, unsigned len, unsigned m, unsigned n ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::element( const unsigned m, const unsigned n ); |
Pascal/Delphi | uses MFstd;
function MF_element( MA:fMatrix; ht, len, m, n:UInt );
procedure MCF_element( var RetVal:fComplex; MA:cfMatrix; ht, len, m, n:UInt ); |
|
Description | The element MAm,n is returned.
Pascal/Delphi only: As fComplex return values are not possible, the MCF_ version stores MAm,n into the variable RetVal.
This function is needed to read elements of dynamically allocated matrices, for which older versions of Borland C++ had a pointer arithmetics bug, and Pascal/Delphi - unlike C - does not provide an own mechanism at all.
MF_element is "read-only". This means, you c a n n o t write something like
MF_element( MX, ht, len, 3, 4 ) := 5;
Write access to individual matrix elements is provided by MF_Pelement |
|
Return value | the matrix element m,n (except complex version in Pascal/Delphi) |
|
|
MFsym_eigenvalues
| MDsym_eigenvalues |
MEsym_eigenvalues |
|
Function | Eigenvalues and/or Eigenvectors of a real symmetric matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MFsym_eigenvalues( fVector EigVals, fMatrix EigVecs, fMatrix A, unsigned len, int CalcEigenVec ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::sym_eigenvalues( matrix<T> EigVecs, const matrix<T>& MA, int CalcEigenVec );
void matrix<T>::sym_eigenvalues( matrix<T>* EigVecs, const matrix<T>& MA, int CalcEigenVec ); |
Pascal/Delphi | uses MFstd;
procedure MFsym_eigenvalues( EigVals:fVector; EigVecs, MA:fMatrix; len:UInt; CalcEigenVec:IntBool ); |
|
Description | The eigenvalues, with or without the eigenvectors, of MA are calculated. This function is for symmetric real matrices only! It takes the following arguments:
- EigVals: a vector in which the eigenvalues will be returned
- EigVecs: a matrix whose columns will be filled with the eigenvectors
- MA: the input matrix, which may or may not be overwritten by EigVecs
- len: the length of the rows (which is the same as the height of the columns, as MA must be a symmetric square matrix)
- CalcEigenVec: an int or IntBool, deciding if only the eigenvalues are needed (CalcEigenVec = FALSE or 0), or if the eigenvectors are desired as well (CalcEigenVec = TRUE or 1). Calculating the eigenvalues alone, without the eigenvectors, can speed up the calculation by up to a factor of two.
|
|
|
MCF_equ0 |
MCD_equ0 |
MCE_equ0 |
|
Function | initialize a matrix with all elements set to 0 |
|
Syntax C/C++ | #include <MFstd.h>
void MF_equ0( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::equ0( ); |
Pascal/Delphi | uses MFstd;
procedure MF_equ0( MA:fMatrix; ht, len:UInt ); |
|
|
|
MCF_equ1 |
MCD_equ1 |
MCE_equ1 |
|
|
Syntax C/C++ | #include <MFstd.h>
void MF_equ1( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::equ1( ); |
Pascal/Delphi | uses MFstd;
procedure MF_equ1( MA:fMatrix; len:UInt ); |
|
Description | MAi,i = 1
MAi,j = 0, i != j |
|
|
MCF_equM |
MCD_equM |
MCE_equM |
|
Function | make one matrix the copy of another |
|
Syntax C/C++ | #include <MFstd.h>
void MF_equM( fMatrix B, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::equM( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_equM( MB, MA:fMatrix; ht, len:UInt ); |
|
|
|
MF_equm1
| MD_equm1 |
ME_equm1 |
MCF_equm1 |
MCD_equm1 |
MCE_equm1 |
|
Function | negative identity matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_equm1( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::equm1( ); |
Pascal/Delphi | uses MFstd;
procedure MF_equm1( MA:fMatrix; len:UInt ); |
|
Description | MAi,i = -1
MAi,j = 0, i != j |
|
|
MF_equMblock
| MD_equMblock |
ME_equMblock |
MCF_equMblock |
MCD_equMblock |
MCE_equMblock |
|
Function | Extract a block from a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_equMblock( fMatrix Sub,
unsigned subHt, unsigned subLen,
fMatrix Srce, unsigned srceHt, unsigned srceLen,
unsigned firstRow, unsigned firstCol ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::equMblock( const matrix<T>& MSrce, const unsigned firstRow, const unsigned firstCol ); |
Pascal/Delphi | uses MFstd;
procedure MF_equMblock( MSub:fMatrix;
subHt, subLen: UInt;
MSrce:fMatrix;
srceHt, srceLen, firstRow, firstCol:UInt ); |
|
Description | MSubi, j = MSrcei+firstRow, j+firstCol, i=0,...,subHt-1; j=0,...,subLen-1 |
|
|
MF_equMblockT
| MD_equMblockT |
ME_equMblockT |
MCF_equMblockT |
MCD_equMblockT |
MCE_equMblockT |
|
Function | Extract and transpose a block from a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_equMblockT( fMatrix Sub,
unsigned subHt, unsigned subLen,
fMatrix Srce, unsigned srceHt, unsigned srceLen,
unsigned firstRow, unsigned firstCol ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::equMblockT( const matrix<T>& MSrce, const unsigned firstRow, const unsigned firstCol ); |
Pascal/Delphi | uses MFstd;
procedure MF_equMblockT( MSub:fMatrix;
subHt, subLen: UInt;
MSrce:fMatrix;
srceHt, srceLen, firstRow, firstCol:UInt ); |
|
Description | MSubj, i = MSrcei+firstRow, j+firstCol, i=0,...,subLen-1; j=0,...,subHt-1 |
|
|
MF_FFTtoC
| MD_FFTtoC |
ME_FFTtoC |
|
Function | two-dimensional Fast Fourier Transform |
|
Syntax C/C++ | #include <MFstd.h>
void MF_FFT( fMatrix Y, fMatrix X, unsigned ht, unsigned len, int dir );
void MCF_FFT( cfMatrix Y, cfMatrix X, unsigned ht, unsigned len, int dir );
void MF_FFTtoC( cfMatrix Y, fMatrix X, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::FFT( const matrix<T>& MX, int dir );
void matrix<complex<T> >::FFT( const matrix<complex<T> >& MX, int dir );
void matrix<complex<T> >::FFTtoC( const matrix<T>& MX ); |
Pascal/Delphi | uses MFstd;
procedure MF_FFT( MY, MX:fMatrix; ht, len:UInt; dir:Integer );
procedure MCF_FFT( MY, MX:cfMatrix; ht, len:UInt; dir:Integer );
procedure MF_FFTtoC( MY:cfMatrix; MX:fMatrix; ht, len:UInt ); |
|
Description | The Fourier transform of MX is calculated and stored in MY. The forward transform is obtained by setting dir = 1, the inverse (or backward) transform by setting dir = -1. A Fast Fourier Transform algorithm is used that requires both ht and len to be powers of 2.
Complex version: Both MX and the output MY are complex matrices.
Real-to-complex version: The input matrix MX is real. The output matrix MY is complex. As this function can only perform a forward transform, no argument "dir" is needed.
Purely real version: For the forward transform, MX is a real matrix. The output MY is also defined as fMatrix, although it consists of complex numbers. The reason is that, just as in the one-dimensional case, the symmetry properties of two-dimensional FFT allow to store the result in a packed format, fitting into the same memory space as the input matrix. The order of storage in MY is derived from the ordering in the one-dimensional case, with the packing applied first to all rows, then to the columns. The resulting order is indicated in the following table. U means the uncompressed result.
U0,0.Re | U0,len/2.Re | U0,1.Re | U0,1.Im | ··· | U0,len/2-1.Re | U0,len/2-1.Im |
Uht/2,0.Re | Uht/2,len/2.Re | U1,1.Re | U1,1.Im | ··· | U1,len/2-1.Re | U1,len/2-1.Im |
U1,0.Re | U1,len/2.Re | U2,1.Re | U2,1.Im | ··· | U2,len/2-1.Re | U2,len/2-1.Im |
U1,0.Im | U1,len/2.Im | U3,1.Re | U3,1.Im | ··· | U3,len/2-1.Re | U3,len/2-1.Im |
··· | ··· | ··· | ··· | ··· | ··· | ··· |
Uht/2-1,0.Re | Uht/2-1,len/2.Re | ··· | ··· | ··· | ··· | ··· |
Uht/2-1,0.Im | Uht/2-1,len/2.Im | Uht-1,1.Re | Uht-1,1.Im | ··· | Uht-1,len/2-1.Re | Uht-1,len/2-1.Im |
For inverse real-matrix FFT, the input matrix has to be of this packed-complex format, and you get a real matrix. If you prefer to get the result of forward FFT as a true complex matrix, use MF_FFTtoC.
About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. |
|
Error handling | If either ht or len is not a power of 2, VF_FFT (on which MF_FFT is based) complains "Size must be an integer power of 2" and the program is aborted. |
|
|
MF_filter
| MD_filter |
ME_filter |
MCF_filter |
MCD_filter |
MCE_filter |
|
Function | Spatial frequency filtering |
|
Syntax C/C++ | #include <MFstd.h>
void MF_filter( fMatrix Y, fMatrix X, fMatrix Flt, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::filter( const matrix<T>& MX, const matrix<T>& MFlt ); |
Pascal/Delphi | uses MFstd;
procedure MF_filter( MY, MX, MFlt:fMatrix; ht, len:UInt ); |
|
Description | A spatial frequency filter MFlt is applied to the matrix MX. Internally, this is done by performing a Fourier transform on MX, multiplying the transform with MFlt and transforming the product back into the space domain.
Complex versions: MX, MY and the filter MFlt are complex matrices.
Real versions: MX and MY are real. MFlt has to be in the packed complex format that is obtained by Fourier transforming a real matrix with MF_FFT (see that function for the description of the packed complex format) or by using MF_convolve.
If MX is non-periodic, the edges of the filtered function may be spoiled by wrap-around. See VF_convolve about how to avoid end-effects. As described there for vectors, embed the matrix MX in a larger matrix or remove a possible linear trends in both dimensions.
About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8. |
|
Error handling | If either ht or len is not a power of 2, VF_FFT (on which MF_filter is based) complains "Size must be an integer power of 2" and the program is aborted. |
|
|
|
Function | Calculate a color scale and draw an X-Y coordinate system for matrix color-density plots |
|
Syntax C/C++ | #include <Mgraph.h>
void M_findDensityMapBounds( extended xmin, extended xmax, extended ymin, extended ymax, extended zmin, extended zmax, COLORREF mincolor, COLORREF maxcolor ); |
Pascal/Delphi | uses Mgraph;
procedure M_findDensityMapBounds( xmin, xmax, ymin, ymax, zmin, zmax: Extended; mincolor, maxcolor: COLORREF ); |
|
Description | Similarly to the function V_findAxes for X-Y vector plots, this function calculates a color scale from the parameters mincolor, maxcolor, zmin and zmax, and prepares an X-Y coordinate system for color-density plots of matrices. If necessary, the x and y ranges are slightly enlarged so as to ensure that the grid-lines correspond to exact (rather than only rounded) values. If zero falls into either or both ranges, it will fall onto a grid line.
The user will rarely call this function himself. It is internally called by all functions of the MF_xyzAutoDensityMap and MF_zAutoDensityMap families. |
|
|
MF_fprint
| MD_fprint |
ME_fprint |
MCF_fprint |
MCD_fprint |
MCE_fprint |
|
Function | print a matrix in ASCII format to a stream |
|
Syntax C/C++ | #include <MFstd.h>
void MF_fprint( FILE *stream, fMatrix A, unsigned ht, unsigned len, unsigned linewidth ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::fprint( FILE *stream, unsigned linewidth ); |
Pascal/Delphi | uses MFstd;
{Delphi version:}
procedure MF_fprint( var Stream:TextFile; MA:fMatrix; ht, len, linewidth:UInt );
{Turbo Pascal version:}
procedure MF_fprint( var Stream:Text; MA:fMatrix; ht, len, linewidth:UInt ); |
|
Description | The matrix MA is written to stream. Each line corresponds to one row of the matrix. The lines are numbered. If the specified linewidth is too small to write all columns, rows are cut off.
Printing starts always with a new line. This may lead to an empty line at the beginning. Especially the first line of a file is reserved for a possible headline.
Cartesian complex numbers are printed in braces, with the real and imaginary parts separated by a komma: {Re, Im}.In contrast to MF_write, it is not possible to override the automatic choice of the format used for printing. The number of digits per element is determined by the available space, which depends in turn on the parameters len and linewidth.
|
|
Error handling | if len exceeds the maximum number of entries possible for the linewidth chosen, an error message "Cannot use requested format (too many entries per line)!" is generated; in this case, the program truncates the rows at the maximum number of columns possible. |
|
|
|
Function | de-allocate a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void M_free( void **M ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::free(); |
Pascal/Delphi | uses MFstd;
procedure M_free( M:Pointer ); |
|
Description | The matrix M is freed (i.e. de-allocated). M_free should be used only for the de-allocation of matrices which have previously be allocated by one of the functions of the MF_matrix or MF_matrix0 family. To free several matrices simultaneously, use M_nfree (C/C++ only). To free all allocated vectors and matrices simultaneously, call V_freeAll.
|
|
Error handling | Trying to free a matrix that has already been freed, or that has never been allocated memory, leads to a warning message "Cannot free non-existent vector". Program execution is continued without freeing anything in this case. |
|
|
M_FtoD | M_FtoE | M_CFtoCD | M_CFtoCE |
M_DtoF | M_DtoE | M_CDtoCF | M_CDtoCE |
M_EtoF | M_EtoD | M_CEtoCF | M_CEtoCD |
|
Function | Data type interconversions. |
|
Syntax C/C++ | #include <MDstd.h>
(always include the <M..std.h> file of the destination data-type!)
void M_FtoD( dMatrix Y, fMatrix X, unsigned ht, unsigned len );
(similarly all other functions of this family) |
C++ MatObj | #include <OptiVec.h>
void matrix<double>::FtoD( const matrix<float>& MX ); |
Pascal/Delphi | uses MDstd;
(always include the unit of the destination data-type!)
procedure M_FtoD( MY:dMatrix; MX:fMatrix; ht, len:UInt );
(similarly all other functions of this family) |
|
Description | Each element of MX is converted from the data type specified for MX to the data type specified for MY and stored in MY. |
|
Error handling | OVERFLOW errors may occur in the course of the "down-conversions" (e.g., M_EtoF); by default, the extreme value possible for the destination data type is stored in MY with the correct sign. |
|
|
VF_getLinfitNeglect
| VD_getLinfitNeglect |
VE_getLinfitNeglect |
|
Function | retrieve the current significance threshold for data fitting to linear models |
|
Syntax C/C++ | #include <MFstd.h>
float VF_getLinfitNeglect( void ); |
C++ MatObj | #include <OptiVec.h>
T vector<T>::getLinfitNeglect();
T matrix<T>::getLinfitNeglect(); |
Pascal/Delphi | uses MFstd;
function VF_getLinfitNeglect:Single; |
|
Description | Internally, the linear-fitting functions like VF_linfit employ a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
In the C++ MatObj version, this function takes only the data type from the matrix as whose member function it is called, but has nothing specific to do with it otherwise. |
|
Return value | current significance threshold for linear fitting |
|
|
VF_getNonlinfitOptions
| VD_getNonlinfitOptions |
VE_getNonlinfitOptions |
|
Function | retrieve current set of options for nonlinear fitting |
|
Syntax C/C++ | #include <MFstd.h>
void VF_getNonlinfitOptions( VF_NONLINFITOPTIONS *Options ); |
Pascal/Delphi | uses MFstd;
procedure VF_getNonlinfitOptions( var Options: VF_NONLINFITOPTIONS ); |
|
Description | The nonlinear fitting routines like VF_nonlinfit offer the user a lot of different options, packed into a structure VF_NONLINFITOPTIONS (VD_NONLINFITOPTIONS and VE_NONLINFITOPTIONS for the higher accuracy data-types). These options may be set by the function V_setNonlinfitOptions. To retrieve current settings, use
V_getNonlinfitOptions. |
|
|
MF_Hanning
| MD_Hanning |
ME_Hanning |
|
Function | two-dimensional Hanning window for spatial frequency analysis |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Hanning( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Hanning(); |
Pascal/Delphi | uses MFstd;
procedure MF_Hanning( MA:fMatrix; ht, len:UInt ); |
|
Description | MAi,j = 0.25 * (1 - cos( 2 p i / (ht-1) )) * (1 - cos( 2 p j / (len-1) )) |
|
|
MCF_hermconj
| MCD_hermconj |
MCE_hermconj |
|
Function | Hermitian conjugate of a matrix |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_hermconj( cfMatrix Tr, cfMatrix A, unsigned htTr, unsigned lenTr ); |
C++ MatObj | #include <OptiVec.h>
void matrix<complex<T> >::hermconj( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_hermconj( MTr, MA:cfMatrix; htTr, lenTr:UInt ); |
|
Description | The Hermitian conjugate of a complex matrix is defined as the complex conjugate of its transpose:
MTri,j = MAj,i*
The dimensions fed into this function, htTr and lenTr, refer to the transposed matrix rather than to the input matrix. |
|
|
MCF_HmulM |
MCD_HmulM |
MCE_HmulM |
|
Function | multiply the hermitian conjugate of one matrix by another matrix |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_HmulM( cfMatrix C, cfMatrix A, cfMatrix B, unsigned htA, unsigned lenA, unsigned lenB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<complex<T> >::HmulM( const matrix<complex<T> >& MA, const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_HmulM( MC, MA, MB:cfMatrix; htA, lenA, lenB:UInt ); |
|
Description | MC = MAT* * MB
htA, lenA, and lenB must be specified; the other dimensions are implicitly given as: htB = htA, lenC = lenB, htC = lenA. htA and lenA refer to the original, un-transposed input matrix. |
|
|
|
|
Syntax C/C++ | #include <MFstd.h>
int MF_inv( fMatrix Inv, fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::inv( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
function MF_inv( MInv, MA:fMatrix; len:UInt ):IntBool; |
|
Description | The inverse of the matrix MA is stored in MInv. If MA is non-invertible, the function fails with an error message and returns TRUE (1). Internally, inversion is accomplished via LU decomposition. In order to prevent the function from failing, you can define a minimum pivot for the decomposition, using MF_LUDsetEdit. In that case, any matrix is made invertible, and MF_inv returns always FALSE (0). Only a call to MF_LUDresult will tell you if editing has actually been necessary to avoid a singularity. If such a result is still useful, shall depend on your specific application. |
|
Return value | FALSE (0), if no error occurred, otherwise TRUE (non-zero). |
|
|
MF_LequU
| MD_LequU |
ME_LequU |
MCF_LequU |
MCD_LequU |
MCE_LequU |
|
Function | copy upper-diagonal elements into lower-diagonal by index-reflection, so as to get a symmetric matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_LequU( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::LequU( ); |
Pascal/Delphi | uses MFstd;
procedure MF_LequU( MA:fMatrix; len:UInt ); |
|
Description | MAi,j = MAj,i, i > j |
|
|
MF_lincomb
| MD_lincomb |
ME_lincomb |
MCF_lincomb |
MCD_lincomb |
MCE_lincomb |
|
Function | linear combination of two matrices |
|
Syntax C/C++ | #include <MFstd.h>
void MF_lincomb( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len, float CA, float CB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::lincomb( const matrix<T>& MA, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MF_lincomb( MC, MA, MB:fMatrix; ht, len:UInt; CA, CB:Single ); |
|
Description | MC = CA * MA + CB * MB |
|
|
VF_linfit
| VD_linfit |
VE_linfit |
VF_linfitwW |
VD_linfitwW |
VE_linfitwW |
|
Function | Data-fitting to models y=f(x) linear in the parameters |
|
Syntax C/C++ | #include <MFstd.h>
void VF_linfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, ui sizex,
void funcs(fVector BasFuncs, float x, unsigned nfuncs));
void VF_linfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fVector InvVar, ui sizex,
void funcs(fVector BasFuncs, float x, unsigned nfuncs)); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::linfit( const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y,
void funcs(fVector BasFuncs, float x, unsigned nfuncs));
void vector<T>::linfitwW( matrix<T> Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const vector<T>& InvVar,
void funcs(fVector BasFuncs, float x, unsigned nfuncs));
void vector<T>::linfitwW( matrix<T>* Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const vector<T>& InvVar,
void funcs(fVector BasFuncs, float x, unsigned nfuncs)); |
Pascal/Delphi | uses MFstd;
procedure VF_linfit( A:fVector; AStatus:iVector; npars:UInt; X, Y:fVector; sizex:UInt; funcs:Pointer );
procedure VF_linfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; npars:UInt; X, Y, InvVar:fVector; sizex:UInt; funcs:Pointer ); |
|
Description | The input data X, Y (and InvVar) are used to evaluate the parameters ai of a general linear function,
y = a0f0(x) + a1f1(x) + a2f2(x)...
The parameters ai are returned in the vector A.
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
X, Y, InvVar | vectors of size sizex, holding the input data |
funcs | user-defined model function |
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide the vector AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling VF_linfit. npars denotes the total number of parameters in A (not only the free parameters!).
The model function funcs must calculate the individual fi(x) for any argument x and store the fi(x) in a vector BasFuncs of size npars. In C/C++, it has to be defined as
void MyFunc( fVector BasFuncs, float x, unsigned nfuncs)
{
BasFuncs[0] = f0( x );
BasFuncs[1] = f1( x);
. . .
}
and shall be passed to VF_linfit by calling
VF_linfit( A, AStatus, npars, X, Y, sizex, MyFunc );
In Pascal/Delphi, the model function has to be defined as
procedure MyFunc( BasFuncs:fVector; x:Single; nfuncs:UInt );
begin
VF_Pelement( BasFuncs, 0 )^ := f0( x );
VF_Pelement( BasFuncs, 1 )^ := f1( x );
. . .
end;
and shall be passed to VF_linfit by calling
VF_linfit( A, AStatus, npars, X, Y, sizex, @MyFunc );
Note the address-of operator in front of "MyFunc.". In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}.
The functions f0( x ) etc. must not contain the parameters ai.
In the weighted variant, VF_linfitwW, the vector InvVar has to contain the inverse of the variances of the individual X-Y data points, and the matrix Covar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ). Internally, VF_linfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are
set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
|
|
|
MF_linfit
| MD_linfit |
ME_linfit |
MF_linfitwW |
MD_linfitwW |
ME_linfitwW |
|
Function | Data-fitting to models z=f(x, y) linear in the parameters |
|
Syntax C/C++ | #include <MFstd.h>
void MF_linfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, unsigned htZ, unsigned lenZ,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
void MF_linfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, fMatrix InvVar, unsigned htZ, unsigned lenZ,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs)); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::linfit( const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
void vector<T>::linfitwW( matrix<T> Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs));
void vector<T>::linfitwW( matrix<T>* Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar,
void funcs(fVector BasFuncs, float x, float y, unsigned nfuncs)); |
Pascal/Delphi | uses MFstd;
procedure MF_linfit( A:fVector; AStatus:iVector; npars:UInt; X, Y:fVector; MZ:fMatrix; htZ, lenZ:UInt; funcs:Pointer );
procedure MF_linfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; npars:UInt; X, Y:fVector; MZ, MInvVar:fMatrix; htZ, lenZ:UInt; funcs:Pointer ); |
|
Description | The input data X, Y, MZ (and MInvVar) are used to evaluate the parameters ai of a general linear function,
z = a0f0(x, y) + a1f1(x, y) + a2f2(x, y)...
The parameters ai are returned in the vector A.
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
X, Y | vectors of size lenZ and htZ, respectively, spanning the x-y coordinate system of the matrix MZ |
MZ, MInvVar | matrices of dimensions [htZ, lenZ], holding the input data and, in the weighted variant, the inverse of their variances |
funcs | user-defined model function |
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide the vector AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling MF_linfit. npars denotes the total number of parameters in A (not only the free parameters!).
You must provide a model function "funcs" which, for any pair of arguments x, y, must calculate the individual fi(x, y) and store them in a vector BasFuncs of size npars. In C/C++, it has to be defined as
void MyFunc( fVector BasFuncs, float x, float y, unsigned nfuncs);
{
BasFuncs[0] = f0( x, y );
BasFuncs[1] = f1( x, y);
. . .
}
and shall be passed to MF_linfit by calling
MF_linfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, MyFunc );
In Pascal/Delphi, the model function has to be defined as
procedure MyFunc( BasFuncs:fVector; x, y:Single; nfuncs:UInt );
begin
VF_Pelement( BasFuncs, 0 )^ := f0( x, y );
VF_Pelement( BasFuncs, 1 )^ := f1( x, y );
. . .
end;
and shall be passed to MF_linfit by calling
MF_linfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, @MyFunc );
Note the address-of operator in front of "MyFunc.". In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}.
The functions f0( x, y ) etc. must not contain the parameters ai.
In the weighted variant, MF_linfitwW, the matirx MInvVar has to contain the inverse of the variances of the individual X-Y-Z data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
Internally, MF_linfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are
set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
|
|
|
MF_LUdecompose
| MD_LUdecompose |
ME_LUdecompose |
MCF_LUdecompose |
MCD_LUdecompose |
MCE_LUdecompose |
|
|
Syntax C/C++ | #include <MFstd.h>
int MF_LUdecompose( fMatrix LU, uVector Ind, fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::LUdecompose( vector<unsigned> Ind, const matrix<T>& MA );
void matrix<T>::LUdecompose( vector<unsigned>* Ind, const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
function MF_LUdecompose( MLU:fMatrix; Ind:uVector; MA:fMatrix; len:UInt ):Integer; |
|
Description | MA is decomposed into a product MA = L * U, where L is lower-triangular with the diagonal elements equal to 1, and U is upper-triangular. As the combined number of non-trivial elements of L and U just fit into a matrix of the same dimensions as MA, the result is stored in a single matrix MLU rather than in to distinct matrices L and U. Actually, it is not the "true" matrices L and U which are combined into MLU, but rather a row-wise permutation, whose indices are output in the vector Ind. The return value indicates if the number of permuations was even (+1) or uneven (-1).
MA may or may not be overwritten by MLU. To check if MF_LUdecompose was successful, call MF_LUDresult, whose return value will be FALSE (0), if the MA could be decomposed, and TRUE (1) for singular MA.
There are applications where it makes sense to make near-singular matrices decomposable by "pivot editing": If, in the partial pivoting process employed in the decomposition and inversion, no diagonal element larger than the threshold is available, the scaling of the matrix is done with the threshold value rather than with the tiny diagonal element. That way, divisions by (near-)zero are avoided. This pivot editing can be chosen through a call to MF_LUDsetEdit. By default, pivot editing is switched off.
Please note that the present implementation of this function does not employ the fastest possible algorithm. In order to avoid excessive accumulation of round-off error, all dot products are internally summed up in double or extended precision, thus precluding the use of the faster SIMD instructions. |
|
Error handling | In the case of a singular matrix, MLU will be undefined, and an internal flag is set, but no error message is generated. To check if an error occurred, you must call MF_LUDresult. |
|
Return value | +1 or -1, indicating even or uneven number of row permutations |
|
|
MF_LUdet
| MD_LUdet |
ME_LUdet |
MCF_LUdet |
MCD_LUdet |
MCE_LUdet |
|
Function | determinant of an LU decomposed matrix |
|
Syntax C/C++ | #include <MFstd.h>
float MF_LUdet( fMatrix LU, unsigned len, int permut ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::LUdet( const matrix<T>& MLU, int permut ); |
Pascal/Delphi | uses MFstd;
function MF_LUdet( MLU:fMatrix; len:UInt; permut:Integer ): Single; |
|
Description | MF_LUdet calculates the determinant of matrix already decomposed into LU form, and return it as a scalar. The argument permut must be +1 or -1, as given by the return value of MF_LUdecompose |
|
|
|
MF_LUDgetEdit
| MD_LUDgetEdit |
ME_LUDgetEdit |
MCF_LUDgetEdit |
MCD_LUDgetEdit |
MCE_LUDgetEdit |
|
Function | retrieve pivot-editing threshold for LU decomposition |
|
Syntax C/C++ | #include <MFstd.h>
float MF_LUDgetEdit( void ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::LUDgetEdit( ); |
Pascal/Delphi | uses MFstd;
function MF_LUDgetEdit: Single; |
|
|
|
MF_LUDresult
| MD_LUDresult |
ME_LUDresult |
MCF_LUDresult |
MCD_LUDresult |
MCE_LUDresult |
|
Function | check if the last operation utilizing LU decomposition worked error-free |
|
Syntax C/C++ | #include <MFstd.h>
int MF_LUDresult( void ); |
C++ MatObj | #include <OptiVec.h>
int matrix<T>::LUDresult( ); |
Pascal/Delphi | uses MFstd;
function MF_LUDresult: IntBool; |
|
Description | After a call to MF_LUdecompose or any of the functions internally relying on LU decomposition (like MF_inv, MF_solve), the result should be checked by MF_LUDresult. If LU decomposition was successful, MF_LUDresult returns FALSE (0); if MA was (nearly) singular, TRUE (1) is returned. |
|
|
|
MF_LUDsetEdit
| MD_LUDsetEdit |
ME_LUDsetEdit |
MCF_LUDsetEdit |
MCD_LUDsetEdit |
MCE_LUDsetEdit |
|
Function | set pivot-editing threshold for LU decomposition |
|
Syntax C/C++ | #include <MFstd.h>
void MF_LUDsetEdit( float Thresh ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::LUDsetEdit( const T& Thresh ); |
Pascal/Delphi | uses MFstd;
procedure MF_LUDsetEdit( Thresh:Single ); |
|
|
|
MF_LUimprove
| MD_LUimprove |
ME_LUimprove |
MCF_LUimprove |
MCD_LUimprove |
MCE_LUimprove |
|
Function | iterative improvement of the solution of a linear system solved by LU decomposition |
|
Syntax C/C++ | #include <MFstd.h>
void MF_LUimprove( fVector X, fVector B, fMatrix A, fMatrix LU, uVector Ind, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::LUimprove( const vector<T> B, const matrix<T>& MA, const matrix<T>& MLU, const vector<unsigned>& Ind ); |
Pascal/Delphi | uses MFstd;
procedure MF_LUimprove( X, B:fVector; MA, MLU:fMatrix; Ind:uVector; len:UInt ); |
|
Description | Especially for large matrices, accumulated round-off error in LU decomposition may become quite noticable. This round-off error will translate into inaccurate results of MF_LUsolve. If the input matrix was not overwritten by the out put matrix in the initial call to MF_LUdecompose, you may call MF_LUimprove after MF_LUsolve to improve the accuracy by iteration. MF_LUimprove needs the output vector X of MF_LUsolve, the right-hand-side vector B of the linear system, and both the original matrix MA and its raw LU-decomposed form MLU along with its permutation indices, Ind, as arguments. |
|
|
MF_LUinv
| MD_LUinv |
ME_LUinv |
MCF_LUinv |
MCD_LUinv |
MCE_LUinv |
|
Function | invert a matrix already decomposed into LU form |
|
Syntax C/C++ | #include <MFstd.h>
void MF_LUinv( fMatrix Inv, fMatrix LU, uVector Ind, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::LUinv( const matrix<T>& MLU, const vector<unsigned>& Ind ); |
Pascal/Delphi | uses MFstd;
procedure MF_LUinv( MInv, MLU:fMatrix; Ind:uVector; len:UInt ); |
|
Description | MF_LUinv inverts a matrix already decomposed into LU form. Along with the matrix MLU, its permutation indices are needed in the vector Ind as output by MF_LUdecompose |
|
|
MF_LUsolve
| MD_LUsolve |
ME_LUsolve |
MCF_LUsolve |
MCD_LUsolve |
MCE_LUsolve |
|
Function | solve a linear system MA * X = B, where MA has already been decomposed into LU form |
|
Syntax C/C++ | #include <MFstd.h>
void MF_LUsolve( fVector X, fMatrix LU, fVector B, uVector Ind, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::LUsolve( const matrix<T>& MLU, const vector<T>& B, const vector<unsigned>& Ind ); |
Pascal/Delphi | uses MFstd;
procedure MF_LUsolve( X:fVector; MLU:fMatrix; B:fVector; Ind:uVector;
len:UInt ); |
|
Description | The linear system MA * X = B is solved for the vector X. Instead of MA itself, this function expects the LU decomposed form of MA as the input matrix MLU, along with its row-permutation indices in the vector Ind as output by MF_LUdecompose.
If the original matrix MA is still available, it is recommended to "fine-polish" the result by calling MF_LUimprove. In comparison to the LU decomposition and back-substitution already performed, this iterative improvement takes very little time, but it can lead to an appreaciable improvement of the solution and often even save solutions which otherwise would be ruined by round-off error. |
|
|
MF_matrix
| MD_matrix |
ME_matrix |
MCF_matrix |
MCD_matrix |
MCE_matrix |
|
Function | Memory allocation for a matrix |
|
Syntax C/C++ | #include <MFstd.h>
fMatrix F_matrix( unsigned ht, unsigned len ); |
Pascal/Delphi | uses MFstd;
function MF_matrix( ht, len:UInt ): fMatrix; |
|
Description | Based on memory model and environment, the most appropriate allocation procedure is chosen by these functions. Failure to allocate memory always leads to an error message and a subsequent program abort (similar to the error handling of the "new" operator). To release the memory thus allocated, M_free, M_nfree, or V_freeAll should be used (M_nfree only in C/C++).
Note: the declaration of a matrix (e.g., as fMatrix) reserves only a name, but no memory!
See chapter 4.1 if you are interested in details of the implementation.
|
|
Error handling | If there is not enough memory available, or if size is zero, an error message "Not enough memory" is displayed and the program aborted.
16-bit models:
If more than 64 kB of memory are requested, an error message "Vector > 64 kB not possible" is displayed and the program aborted (except in the model HUGE). If any of the two matrix dimensions exceeds the 64 kB limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted, even in the model HUGE.
32-bit:
If more than 4 GB of memory are requested, an error message "Vector > 4 GB not possible" is displayed and the program aborted. If already a single matrix dimensions exceeds this limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted. |
|
Return value | C/C++: Pointer to the array of row pointers
Pascal/Delphi: Pointer to the allocated memory |
|
|
MF_matrix0
| MD_matrix0 |
ME_matrix0 |
MCF_matrix0 |
MCD_matrix0 |
MCE_matrix0 |
|
Function | allocate memory for a matrix and initialize all elements with 0 |
|
Syntax C/C++ | #include <MFstd.h>
fMatrix F_matrix0( unsigned ht, unsigned len ); |
Pascal/Delphi | uses MFstd;
function MF_matrix0( ht, len:UInt ): fMatrix; |
|
Description | The functions of this family are almost identical to those of the MF_matrix family; in addition to allocating memory, they initialize all elements with 0. (Calls to MF_matrix and MF_matrix0 may be mixed; they and the vector allocation functions, VF_vector etc. use the same tables to keep track of the handles and pointers). For further information, see MF_matrix. |
|
Error handling | If there is not enough memory available, or if size is zero, an error message "Not enough memory" is displayed and the program aborted.
16-bit models:
If more than 64 kB of memory are requested, an error message "Vector > 64 kB not possible" is displayed and the program aborted (except in the model HUGE). If any of the two matrix dimensions exceeds the 64 kB limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted, even in the model HUGE.
32-bit:
If more than 4 GB of memory are requested, an error message "Vector > 4 GB not possible" is displayed and the program aborted. If already a single matrix dimensions exceeds this limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted. |
|
Return value | C/C++: Pointer to the array of row pointers
Pascal/Delphi: Pointer to the allocated memory |
|
|
MF_MatrixTo2DArray
| MD_MatrixTo2DArray |
ME_MatrixTo2DArray |
MCF_MatrixTo2DArray |
MCD_MatrixTo2DArray |
MCE_MatrixTo2DArray |
|
Function | convert OptiVec matrix into 2D-array of Delphi 4 or higher |
|
Syntax C/C++ | N.A. |
Pascal/Delphi | uses VecLib, MFstd;
type fArray = array of Single;
type f2DArray = array of fArray;
procedure MF_MatrixTo2DArray( DelphiArr:f2DArray; MF:fMatrix; ht,len:UInt); |
|
Description | This function is necessary only for Delphi 4 or higher. (Previous versions of Borland Pascal/Delphi did not support dynamically allocated matrices.) It converts OptiVec matrices into two-dimensional Delphi arrays. Note that, unlike static Pascal/Delphi matrices, the dynamic matrices of Delphi 4+ cannot directly be passed to OptiVec functions, but have to be converted first by calling MF_2DArrayToMatrix. If you ever need an OptiVec matrix back into Delphi format, this is done by the present function. |
|
|
MCF_mulC |
MCD_mulC |
MCE_mulC |
MCF_mulReC |
MCD_mulReC |
MCE_mulReC |
|
Function | multiply all matrix element by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_mulC( fMatrix B, fMatrix A, unsigned ht, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::mulC( const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_mulC( MB, MA:fMatrix; ht, len:UInt; C:Single ); |
|
Description | MBij = MAij + C |
|
|
|
Function | multiply a row vector by a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void VF_mulM( fVector Y, fVector X, fMatrix A, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::mulM( const vector<T>& X, const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure VF_mulM( Y, X:fVector; MA:fMatrix; htA, lenA:UInt ); |
|
Description | Y = X * MA;
the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = htA, sizY = lenA. |
|
|
MCF_mulM |
MCD_mulM |
MCE_mulM |
|
Function | matrix multiplication |
|
Syntax C/C++ | #include <MFstd.h>
void MF_mulM( fMatrix C, fMatrix A, fMatrix B, unsigned htA, unsigned lenA, unsigned lenB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::mulM( const matrix<T>& MA, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MF_mulM( MC, MA, MB:fMatrix; htA, lenA, lenB:UInt ); |
|
Description | MC = MA * MB
htA, lenA, and lenB must be specified; the other dimensions are implicitly given as: htB = lenA, lenC = lenB, htC = htA. |
|
|
MFdia_mulM
| MDdia_mulM |
MEdia_mulM |
MCFdia_mulM |
MCDdia_mulM |
MCEdia_mulM |
|
Function | multiplication of a diagonal matrix and a general matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MFdia_mulM( fMatrix C, fVector MADia, fMatrix B, unsigned lenA, unsigned lenB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::dia_mulM( const vector<T>& MADia, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MFdia_mulM( MC:fMatrix; MADia: fVector; MB:fMatrix; lenA, lenB:UInt ); |
|
Description | MC = MADia * MB
The vector MAdia represents the diagonal matrix MA. (A matrix is called diagonal, it it has non-zero elements only on the diagonal). lenA, and lenB must be specified; htB is equal to lenA. |
|
|
MF_mulMdia
| MD_mulMdia |
ME_mulMdia |
MCF_mulMdia |
MCD_mulMdia |
MCE_mulMdia |
|
Function | multiply a general matrix by a diagonal matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_mulMdia( fMatrix C, fMatrix A, fVector MBDia, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::mulMdia( const matrix<T>& MA, const vector<T>& MBDia, ); |
Pascal/Delphi | uses MFstd;
procedure MF_mulMdia( MC, MA:fMatrix; MBDia:fVector; htA, lenA:UInt ); |
|
Description | MC = MA * MBDia.
htA and lenA must be specified; sizB = lenA. |
|
|
MCF_mulMH |
MCD_mulMH |
MCE_mulMH |
|
Function | multiply one complex matrix by the hermitian conjugate of another |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_mulMH( cfMatrix C, cfMatrix A, cfMatrix B, unsigned htA, unsigned lenA, unsigned htB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<complex<T> >::mulMH( const matrix<complex<T> >& MA, const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_mulMH( MC, MA, MB:cfMatrix; htA, lenA, htB:UInt ); |
|
Description | MC = MA * MBT *.
htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = lenA, lenC = htB, htC = htA. |
|
|
MF_mulMT
| MD_mulMT |
ME_mulMT |
MCF_mulMT |
MCD_mulMT |
MCE_mulMT |
|
Function | multiply one matrix by the transpose of another |
|
Syntax C/C++ | #include <MFstd.h>
void MF_mulMT( fMatrix C, fMatrix A, fMatrix B, unsigned htA, unsigned lenA, unsigned htB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::mulMT( const matrix<T>& MA, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MF_mulMT( MC, MA, MB:fMatrix; htA, lenA, htB:UInt ); |
|
Description | MC = MA * MBT.
htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = lenA, lenC = htB, htC = htA. |
|
|
MFdia_mulMT
| MDdia_mulMT |
MEdia_mulMT |
MCFdia_mulMT |
MCDdia_mulMT |
MCEdia_mulMT |
|
Function | multiply a diagonal matrix by the transpose of a general matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MFdia_mulMT( fMatrix C, fVector MADia, fMatrix B, unsigned htB, unsigned lenB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::dia_mulMT( const vector<T>& MADia, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MFdia_mulMT( MC:fMatrix; MADia: fVector; MB:fMatrix; htB, lenB:UInt ); |
|
Description | MC = MADia * MBT
htB and lenB must be specified; sizA equals lenB. |
|
|
VF_mulMT
| VD_mulMT |
VE_mulMT |
|
Function | multiply a row vector by the transpose of a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void VF_mulMT( fVector Y, fVector X, fMatrix A, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::mulMT( const vector<T>& X, const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure VF_mulMT( Y, X:fVector; MA:fMatrix; htA, lenA:UInt ); |
|
Description | Y = X * MAT
The dimensions htA and lenA refer to the original (rather than the intermediate transposed) matrix MA; the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = lenA, sizY = htA. |
|
|
VF_multiLinfit
| VD_multiLinfit |
VE_multiLinfit |
VF_multiLinfitwW |
VD_multiLinfitwW |
VE_multiLinfitwW |
|
Function | fit multiple X-Y data sets to a common model function, linear in its parameters |
|
Syntax C/C++ | #include <MFstd.h>
void VF_multiLinfit( fVector A, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments,
void (*funcs)(fVector BasFuncs, float x,unsigned nfuncs, unsigned iexperiment) );
void VF_multiLinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments,
void (*funcs)(fVector BasFuncs, float x, unsigned nfuncs, unsigned iexperiment) ); |
Pascal/Delphi | uses MFstd;
procedure VF_multiLinfit( A:fVector; AStatus:iVector; nParameters:UInt; ListOfExperiments: PVF_EXPERIMENT; nexperiments:UInt; funcs: Pointer );
procedure VF_multiLinfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; nParameters:UInt; ListOfExperiments:PVF_EXPERIMENT; nexperiments:UInt; funcs:Pointer ); |
|
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameters ai of a general linear function,
y = a0f0(x) + a1f1(x) + a2f2(x)...
The parameters ai are returned in the vector A.
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
ListOfExperiments | input data, see chap. 13.4 |
nexperiments | number of data sets in ListOfExperiments |
funcs | user-defined model function |
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling VF_multiLinfit. The argument npars denotes the total number of parameters in A (not only the free parameters!).
The input data must be combined into sets of the type VF_EXPERIMENT. Assuming you have two sets of X-Y data, contained in the vectors X1, Y1 (and, for VF_multiLinfitwW, InvVar1) of size1 elements, and X2, Y2 (and InvVar2) of size2 elements, you have to construct a list of experiments as in the following example:
| Constructing list of experiments in C/C++ |
VF_EXPERIMENT ExpList[2];
ExpList[0].X = X1; ExpList[0].Y = Y1; ExpList[0].size = size1;
ExpList[1].X = X2; ExpList[1].Y = Y2; ExpList[1].size = size2;
/* for the weighted variant, set additionally: */
ExpList[0].InvVar = InvVar1; ExpList[0].WeightOfExperiment = wt1;
ExpList[1].InvVar = InvVar2; ExpList[1].WeightOfExperiment = wt2;
| Constructing list of experiments in Pascal/Delphi |
var ExpList: array[0..1] of VF_EXPERIMENT;
begin
...
ExpList[0].X := X1; ExpList[0].Y := Y1;
ExpList[0].size := size1;
ExpList[1].X := X2; ExpList[1].Y := Y2;
ExpList[1].size := size2;
(* for the weighted variant, set additionally: *)
ExpList[0].InvVar := InvVar1;
ExpList[0].WeightOfExperiment := wt1;
ExpList[1].InvVar := InvVar2;
ExpList[1].WeightOfExperiment := wt2;
...
end;
| Both C/C++ and Pascal/Delphi |
You must provide a model function "funcs" which, for any argument x, must calculate the individual basis functions fi(x) and store them in a vector BasFuncs. The model function has to be defined as
| Model function for C/C++ |
void MyFunc( fVector BasFuncs, float x, unsigned nfuncs, unsigned iexperiment )
{
BasFuncs[0] = f0( x );
BasFuncs[1] = f1( x);
...
}
and shall be passed to VF_multiLinfit by calling
VF_multiLinfit( A, AStatus, npars, ExpList, 2, MyFunc );
| Model function for Pascal/Delphi |
procedure MyFunc( BasFuncs:fVector; x:Single; nfuncs, iexperiment:UInt );
begin
VF_Pelement( BasFuncs, 0 )^ := f0( x );
VF_Pelement( BasFuncs, 1 )^ := f1( x );
...
end;
This model function shall be passed to VF_multiLinfit by calling
VF_multiLinfit( A, AStatus, npars, @ExpList, 2, @MyFunc );
Note the address-of operators in front of "ExpList" (static Pascal array passed to OptiVec function) and "MyFunc." (pointer to the function MyFunc). In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}.
| Both C/C++ and Pascal/Delphi |
The argument iexperiment with which MyFunc shall be called by VF_multiLinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's Y values might be shifted by a constant C. In this case, A has to contain as many shifts C as there are experiments. In MyFunc, you would have to code this as (in C/C++; you will easily translate this into Pascal/Delphi):
if( iexperiment == 0 ) { BasFuncs[2] = 1; BasFuncs[3] = 0; }
else {BasFuncs[2] = 0; BasFuncs[3] = 1; }
The functions f0( x ) etc. must not contain the parameters ai. In the weighted variant, the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ). Internally, VF_multiLinfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect. |
|
|
MF_multiLinfit
| MD_multiLinfit |
ME_multiLinfit |
MF_multiLinfitwW |
MD_multiLinfitwW |
ME_multiLinfitwW |
|
Function | fit multiple X-Y-Z data sets to a common model function, linear in its parameters |
|
Syntax C/C++ | #include <MFstd.h>
void MF_multiLinfit( fVector A, iVector AStatus, unsigned npars, MF_EXPERIMENT *ListOfExperiments, unsigned nexperiments,
void (*funcs)(fVector BasFuncs, float x, float y, unsigned nfuncs, unsigned iexperiment) );
void MF_multiLinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, MF_EXPERIMENT *ListOfExperiments, unsigned nexperiments,
void (*funcs)(fVector BasFuncs, float x, float y, unsigned nfuncs, unsigned iexperiment) ); |
Pascal/Delphi | uses MFstd;
procedure MF_multiLinfit( A:fVector; AStatus:iVector; nParameters:UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments:UInt; funcs: Pointer );
procedure MF_multiLinfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; nParameters:UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments:UInt; funcs: Pointer ); |
|
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameters ai of a general linear function,
z = a0f0(x,y) + a1f1(x,y) + a2f2(x,y)...
The parameters ai are returned in the vector A.
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
ListOfExperiments | input data, see chap. 13.4 |
nexperiments | number of data sets in ListOfExperiments |
funcs | user-defined model function |
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling MF_multiLinfit. The argument npars denotes the total number of parameters in A (not only the free parameters!).
The input data must be combined into sets of the type MF_EXPERIMENT. Let us assume you have two sets of X-Y-Z data, each with the vectors X and Y for the independent variables, the matrix MZ for the z=f(x,y) values and, for MF_multiLinfitwW, the weights of all points in MInvVar. The matrix dimensions are htZ (equal to sizeY) and lenZ (equal to sizeX). Now you have to construct a list of experiments as in the following example:
| Constructing list of experiments in C/C++ |
MF_EXPERIMENT ExpList[2];
ExpList[0].X = X1; ExpList[0].Y = Y1;
ExpList[0].MZ = MZ1;
ExpList[0].htZ = htZ1; ExpList[0].lenZ = lenZ1;
ExpList[1].X = X1; ExpList[1].Y = Y2;
ExpList[1].MZ = MZ2;
ExpList[1].htZ = htZ2; ExpList[1].lenZ = lenZ2;
/* for the weighted variant, set additionally: */
ExpList[0].MInvVar = MInvVar1;
ExpList[0].WeightOfExperiment = wt1;
ExpList[1].MInvVar = MInvVar2;
ExpList[1].WeightOfExperiment = wt2;
| Constructing list of experiments in Pascal/Delphi |
var ExpList: array[0..1] of MF_EXPERIMENT;
begin
...
ExpList[0].X := X1; ExpList[0].Y := Y1;
ExpList[0].MZ := MZ1;
ExpList[0].htZ := htZ1; ExpList[0].lenZ := lenZ1;
ExpList[1].X := X2; ExpList[1].Y := Y2;
ExpList[1].MZ := MZ2;
ExpList[1].htZ := htZ2; ExpList[1].lenZ := lenZ2;
(* for the weighted variant, set additionally: *)
ExpList[0].MInvVar := MInvVar1;
ExpList[0].WeightOfExperiment := wt1;
ExpList[1].MInvVar := MInvVar2;
ExpList[1].WeightOfExperiment := wt2;
...
end;
| Both C/C++ and Pascal/Delphi |
You must provide a model function "funcs" which, for any argument x, must calculate the individual basis functions fi(x,y) and store them in a vector BasFuncs. The model function has to be defined as
| Model function for C/C++ |
void MyFunc( fVector BasFuncs, float x, float y, unsigned nfuncs, unsigned iexperiment )
{
BasFuncs[0] = f0( x, y );
BasFuncs[1] = f1( x, y );
...
}
and shall be passed to MF_multiLinfit by calling
MF_multiLinfit( A, AStatus, npars, ExpList, 2, MyFunc );
| Model function for Pascal/Delphi |
procedure MyFunc( BasFuncs:fVector; x, y:Single; nfuncs, iexperiment:UInt );
begin
VF_Pelement( BasFuncs, 0 )^ := f0( x, y );
VF_Pelement( BasFuncs, 1 )^ := f1( x, y );
...
end;
This model function shall be passed to MF_multiLinfit by calling
MF_multiLinfit( A, AStatus, npars, @ExpList, 2, @MyFunc );
Note the address-of operators in front of "ExpList" (static Pascal array passed to OptiVec function) and "MyFunc." (pointer to the function MyFunc). In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}.
| Both C/C++ and Pascal/Delphi |
The argument iexperiment with which MyFunc shall be called by MF_multiLinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's MZ values might be shifted by a constant C. In this case, A has to contain as many shifts Ci as there are experiments. In MyFunc, you would have to code this as (in C/C++; you will easily translate this into Pascal/Delphi yourself):
if( iexperiment == 0 ) { BasFuncs[2] = 1; BasFuncs[3] = 0; }
else {BasFuncs[2] = 0; BasFuncs[3] = 1; }
The functions f0( x,y ) etc. must not contain the parameters ai. In the weighted variant, the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
Internally, MF_multiLinfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect. |
|
|
VF_multiNonlinfit
| VD_multiNonlinfit |
VE_multiNonlinfit |
VF_multiNonlinfitwW |
VD_multiNonlinfitwW |
VE_multiNonlinfitwW |
|
Function | fit multiple X-Y data sets to a common model function, possibly non-linear in its parameters |
|
Syntax C/C++ | #include <MFstd.h>
float VF_multiNonlinfit( fVector A, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments,
void (*modelfunc)(fVector YModel, fVector XModel, ui size, unsigned iexperiment),
void (*derivatives)(fVector dYdAi,fVector X, ui size, unsigned ipar, unsigned iexperiment) );
float VF_multiNonlinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments,
void (*modelfunc)(fVector YModel, fVector X, ui size, unsigned iexperiment),
void (*derivatives)(fVector dYdAi, fVector X, ui size, unsigned ipar, unsigned iexperiment) ); |
Pascal/Delphi | uses VFmnlfit;
function VF_multiNonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; ListOfExperiments: PVF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single;
function VF_multiNonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; ListOfExperiments: PVF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single; |
|
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameter array A with npars elements ai of an arbitrary model function y = f(x).
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
ListOfExperiments | input data, see chap. 13.4 |
nexperiments | number of data sets in ListOfExperiments |
modelfunc | user-defined model function |
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters |
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling VF_multiNonlinfit. The better your initial guess of the parameters, the faster VF_multiNonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!).
The input data must be combined into sets of the type VF_EXPERIMENT. Assuming you have two sets of X-Y data, contained in the vectors X1, Y1 (and, for VF_multiLinfitwW, InvVar1) of size1 elements, and X2, Y2 (and InvVar2) of size2 elements, you have to construct a list of experiments as in the following example:
| Constructing list of experiments in C/C++ |
VF_EXPERIMENT ExpList[2];
ExpList[0].X = X1; ExpList[0].Y = Y1; ExpList[0].size = size1;
ExpList[1].X = X2; ExpList[1].Y = Y2; ExpList[1].size = size2;
/* for the weighted variant, set additionally: */
ExpList[0].InvVar = InvVar1; ExpList[0].WeightOfExperiment = wt1;
ExpList[1].InvVar = InvVar2; ExpList[1].WeightOfExperiment = wt2;
| Constructing list of experiments in Pascal/Delphi |
var ExpList: array[0..1] of VF_EXPERIMENT;
begin
...
ExpList[0].X := X1; ExpList[0].Y := Y1;
ExpList[0].size := size1;
ExpList[1].X := X2; ExpList[1].Y := Y2;
ExpList[1].size := size2;
/* for the weighted variant, set additionally: */
ExpList[0].InvVar := InvVar1;
ExpList[0].WeightOfExperiment := wt1;
ExpList[1].InvVar := InvVar2;
ExpList[1].WeightOfExperiment := wt2;
...
end;
| Both C/C++ and Pascal/Delphi |
You must provide a model function "modelfunc" which, for a given vector of x-values, must calculate the corresponding "theoretical" y-values. In C/C++, it has to be defined as
| Model function for C/C++ |
void _cdecl MyFunc( fVector Y, fVector X, ui size, unsigned iexperiment )
{
for (ui i=0; i<size; i++ )
Y[i] = f( X[i] );
}
f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS).
The argument iexperiment with which MyFunc shall be called by VF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's Y values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like:
if( iexperiment == 0 ) Y[i] *= A[5]; else Y[i] *= A[6];
In addition to the model function, VF_multiNonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for C/C++ |
void _cdecl MyDerivs( fVector dYdAi, fVector X, ui size, unsigned ipar, unsigned iexperiment )
{
ui i;
switch( ipar )
{
case 0: for(i=0; i<size; i++ )
dYdAi[i] = part_derv_of_Y_w_resp_to_A0( X[i] );
break;
case 1: for(i=0; i<size; i++ )
dYdAi[i] = part_derv_of_Y_w_resp_to_A1( X[i] );
break;
default: /* for all derivatives we don't know: */
VF_multiNonlinfit_autoDeriv(
dYdAi, X, size, ipar, iexperiment );
}
}
Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters.
A call to VF_multiNonlinfit will look like:
VF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, MyDerivs );
In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_multiNonlinfit with derivaties = NULL:
VF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, NULL );
| Model function for Pascal/Delphi |
In Pascal/Delphi, the model function has to be defined as
procedure MyFunc( Y, X:fVector; size, iexperiment:UInt );
var i:UInt;
begin
for i:=0 to size-1 do
VF_Pelement( Y, i )^ := f( VF_element( X, i ) );
end;
f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see chapter 13.3).
The argument iexperiment with which MyFunc shall be called by VF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's Y values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like:
if iexperiment = 0 then
VF_Pelement(Y,i)^ := VF_element(Y,i) * VF_element(A,5)
else VF_Pelement(Y,i)^ := VF_element(Y,i) * VF_element(A,6);
In addition to the model function, VF_multiNonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for Pascal/Delphi |
procedure MyDerivs( dYdAi, X:fVector; size, ipar, iexperiment:UInt );
var i:UInt;
begin
case ipar of
0: begin
for i:=0 to size-1 do
VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end;
1: begin
for i:=0 to size-1 do
VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end;
else (* for all derivatives we don't know: *)
VF_multiNonlinfit_autoDeriv(
dYdAi, X, size, ipar, iexperiment );
end;
end;
Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters.
A call to VF_multiNonlinfit will look like:
VF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, @MyDerivs );
Note the address-of operator in front of "ExpList", "MyFunc.", and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_multiNonlinfit with derivaties = nil:
VF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, nil );
In the weighted variant, VF_multiNonlinfitwW, the vector ExpList[i].InvVar of each experiment has to contain the inverse of the variances of the individual X-Y data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
| Both C/C++ and Pascal/Delphi: |
For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of VF_multiNonlinfit, described here.
|
|
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, VF_nonlinfit and VF_multiNonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run VF_multiNonlinfit and VD_multiNonlinfit in parallel.
These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy. |
|
Error handling | If the number of free parameters (i.e., those with AStatus[i] = 1) exceeds the total number of data points, an error message "Invalid parameter(s)" is generated and the program aborted. |
|
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1 |
|
|
VF_multiNonlinfit_...
| VD_multiNonlinfit_... |
VE_multiNonlinfit_... |
VF_multiNonlinfitwW_... |
VD_multiNonlinfitwW_... |
VE_multiNonlinfitwW_... |
|
|
Syntax C/C++ | #include <MFstd.h>
void VF_multiNonlinfit_autoDeriv( fVector dYdAi, fVector X, ui size, unsigned ipar, unsigned iexperiment );
float VF_multiNonlinfit_getChi2( void );
void VF_multiNonlinfit_getChi2Detail( fVector Chi2Detail );
void VF_multiNonlinfit_getBestValues( fVector ABest );
int VF_multiNonlinfit_getTestDir( void );
unsigned VF_multiNonlinfit_getTestPar( void );
unsigned VF_multiNonlinfit_getTestRun( void );
void VF_multiNonlinfit_stop( void );
(identical syntax for the VF_multiNonlinfitwW_... functions) |
Pascal/Delphi | uses VFmnlfit;
procedure VF_multiNonlinfit_autoDeriv( dYdAi, X:fVector; size, ipar, iex:UInt );
function VF_multiNonlinfit_getChi2: Single;
procedure VF_multiNonlinfit_getChi2Detail( Chi2Detail:fVector );
procedure VF_multiNonlinfit_getBestValues( BestValues: fVector );
function VF_multiNonlinfit_getTestDir: Integer;
function VF_multiNonlinfit_getTestPar: UInt;
function VF_multiNonlinfit_getTestRun: UInt;
procedure VF_multiNonlinfit_stop;
(identical syntax for the VF_multiNonlinfitwW_... functions) |
|
Description | VF_multiNonlinfit_autoDeriv performs a numerical differentiation of a user-provided y=f(x) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to VF_multiNonlinfit. The model function that is differentiated by VF_multiNonlinfit_autoDeriv is the one passed in the same call to VF_multiNonlinfit (see that function for details!).
The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function.
VF_multiNonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before VF_multiNonlinfit has had the chance to calculate c2, VF_multiNonlinfit_getChi2 returns -1.0.
VF_multiNonlinfit_getChi2Detail fills the user-supplied vector Chi2Detail with the individual figures-of-merit (c2iex or, for robust fits, |ciex|) for all experiments. The sum over these individual c2iex or |ciex| values is the best c2 (or |c|) obtained so far, as returned by VF_multiNonlinfit_getChi2.
VF_multiNonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest.
VF_multiNonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions).
VF_multiNonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation.
VF_multiNonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first.
VF_multiNonlinfit_stop makes VF_multiNonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data. |
|
|
MF_multiNonlinfit
| MD_multiNonlinfit |
ME_multiNonlinfit |
MF_multiNonlinfitwW |
MD_multiNonlinfitwW |
ME_multiNonlinfitwW |
|
Function | fit multiple X-Y-Z data sets to a common model function, possibly non-linear in its parameters |
|
Syntax C/C++ | #include <MFstd.h>
float MF_multiNonlinfit( fVector A, iVector AStatus, unsigned npars, MF_EXPERIMENT _VFAR *ListOfExperiments, unsigned nexperiments,
void (*modelfunc)(fMatrix ZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned iexperiment),
void (*derivatives)(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar, unsigned iexperiment) );
float MF_multiNonlinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, MF_EXPERIMENT *ListOfExperiments, unsigned nexperiments,
void (*modelfunc)(fMatrix ZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned iexperiment ),
void (*derivatives)(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar, unsigned iexperiment) ); |
Pascal/Delphi | uses MFmnlfit;
function MF_multiNonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single;
function MF_multiNonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single; |
|
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameter array A with npars elements ai of an arbitrary model function z = f(x, y).
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
ListOfExperiments | input data, see chap. 13.4 |
nexperiments | number of data sets in ListOfExperiments |
modelfunc | user-defined model function |
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters |
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling MF_multiNonlinfit. The better your initial guess of the parameters, the faster MF_multiNonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!).
The input data must be combined into sets of the type MF_EXPERIMENT. Let us assume you have two sets of X-Y-Z data, each with the vectors X and Y for the independent variables, the matrix MZ for the z=f(x,y) values and, for MF_multiLinfitwW, the weights of all points in MInvVar. The matrix dimensions are htZ (equal to sizeY) and lenZ (equal to sizeX). Now you have to construct a list of experiments as in the following example:
| Constructing list of experiments in C/C++ |
MF_EXPERIMENT ExpList[2];
ExpList[0].X = X1; ExpList[0].Y = Y1;
ExpList[0].MZ = MZ1;
ExpList[0].htZ = htZ1; ExpList[0].lenZ = lenZ1;
ExpList[1].X = X1; ExpList[1].Y = Y2;
ExpList[1].MZ = MZ2;
ExpList[1].htZ = htZ2; ExpList[1].lenZ = lenZ2;
/* for the weighted variant, set additionally: */
ExpList[0].MInvVar = MInvVar1;
ExpList[0].WeightOfExperiment = wt1;
ExpList[1].MInvVar = MInvVar2;
ExpList[1].WeightOfExperiment = wt2;
| Constructing list of experiments in Pascal/Delphi |
var ExpList: array[0..1] of MF_EXPERIMENT;
begin
...
ExpList[0].X := X1; ExpList[0].Y := Y1;
ExpList[0].MZ := MZ1;
ExpList[0].htZ := htZ1; ExpList[0].lenZ := lenZ1;
ExpList[1].X := X2; ExpList[1].Y := Y2;
ExpList[1].MZ := MZ2;
ExpList[1].htZ := htZ2; ExpList[1].lenZ := lenZ2;
/* for the weighted variant, set additionally: */
ExpList[0].MInvVar := MInvVar1;
ExpList[0].WeightOfExperiment := wt1;
ExpList[1].MInvVar := MInvVar2;
ExpList[1].WeightOfExperiment := wt2;
...
end;
| Both C/C++ and Pascal/Delphi |
You must provide a model function "modelfunc" which, for a given pair of X, Y vectors, must calculate the corresponding "theoretical" z-values. In C/C++, it has to be defined as
| Model function for C/C++ |
void _cdecl MyFunc( fMatrix Z, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned iexperiment )
{
for (ui i=0; i<htZ; i++ )
for (ui j=0; j<lenZ; j++ )
MZ[i][j] = f( X[j], Y[i] );
}
f( X[j], Y[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS).
The argument iexperiment with which MyFunc shall be called by MF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's MZ values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like:
if( iexperiment == 0 ) MZ[i][j] *= A[5]; else MZ[i][j] *= A[6];
In addition to the model function, MF_multiNonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for C/C++ |
void _cdecl MyDerivs( fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar, unsigned iexperiment )
{
ui i;
switch( ipar )
{
case 0:
for(i=0; i<htZ; i++ )
for( j=0; j<lenZ; j++ )
dZdAi[i][j] = part_derv_MZ_w_resp_to_A0( X[j], Y[i] );
break;
case 1:
for(i=0; i<htZ; i++ )
for( j=0; j<lenZ; j++ )
dZdAi[i][j] = part_derv_MZ_w_resp_to_A1( X[j], Y[i] );
break;
default: /* for all derivatives we don't know: */
MF_multiNonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar, iexperiment );
}
}
Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters.
A call to MF_multiNonlinfit will look like:
MF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, MyDerivs );
In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_multiNonlinfit with derivaties = NULL:
MF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, NULL );
| Model function for Pascal/Delphi |
In Pascal/Delphi, the model function has to be defined as
procedure MyFunc( MZ:fMatrix; htZ, lenZ:UInt; X, Y:fVector; iexperiment:UInt );
var i, j:UInt;
begin
for i:=0 to htZ-1 do
for j:=0 to lenZ-1 do
MF_Pelement( MZ, htZ, lenZ, i, j )^ :=
f( VF_element( X, j ), VF_element( Y, i ) );
end;
f( Xj, Yi ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS).
The argument iexperiment with which MyFunc shall be called by MF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's MZ values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like:
if iexperiment = 0 then
MF_Pelement(MZ, htZ, lenZ, i, j)^ :=
MF_element(MZ, htZ, lenZ, i, j) * VF_element(A,5)
else MF_Pelement(MZ, htZ, lenZ, i, j)^ :=
MF_element(MZ, htZ, lenZ, i, j) * VF_element(A,6);
In addition to the model function, MF_multiNonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for Pascal/Delphi |
procedure MyDerivs( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar, iexperiment:UInt );
var i, j:UInt;
begin
case ipar of
0: begin
for i:=0 to htZ-1 do
for j:=0 to lenZ-1 do
MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A0(VF_element( X, j ), VF_element( Y, i ));
end;
1: begin
for i:=0 to htZ-1 do
for j:=0 to lenZ-1 do
MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A1(VF_element( X, j ), VF_element( Y, i ));
end;
else (* for all derivatives we don't know: *)
MF_multiNonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar );
end;
end;
Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters.
A call to MF_multiNonlinfit will look like:
MF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, @MyDerivs );
Note the address-of operator in front of "ExpList", "MyFunc.", and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_multiNonlinfit with derivaties = nil:
MF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, nil );
In the weighted variant, MF_multiNonlinfitwW, the matrix ExpList[i].MInvVar of each experiment has to contain the inverse of the variances of the individual X-Y-Z data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
| Both C/C++ and Pascal/Delphi: |
For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of MF_multiNonlinfit, described here.
|
|
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, MF_multiNonlinfit and MF_multiNonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run MF_multiNonlinfit and MD_multiNonlinfit in parallel.
These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy. |
|
Error handling | If the number of free parameters (i.e., those with AStatus[i] = 1) exceeds the total number of data points, an error message "Invalid parameter(s)" is generated and the program aborted. |
|
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1 |
|
|
MF_multiNonlinfit_...
| MD_multiNonlinfit_... |
ME_multiNonlinfit_... |
MF_multiNonlinfitwW_... |
MD_multiNonlinfitwW_... |
ME_multiNonlinfitwW_... |
|
|
Syntax C/C++ | #include <MFstd.h>
void MF_multiNonlinfit_autoDeriv( fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar, unsigned iex );
float MF_multiNonlinfit_getChi2( void );
void MF_multiNonlinfit_getChi2Detail( fVector Chi2Detail );
void MF_multiNonlinfit_getBestValues( fVector ABest );
int MF_multiNonlinfit_getTestDir( void );
unsigned MF_multiNonlinfit_getTestPar( void );
unsigned MF_multiNonlinfit_getTestRun( void );
void MF_multiNonlinfit_stop( void );
(identical syntax for the MF_nonlinfitwW_... functions) |
Pascal/Delphi | uses MFmnlfit;
procedure MF_multiNonlinfit_autoDeriv( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar, iex: UInt );
function MF_multiNonlinfit_getChi2: Single;
procedure MF_multiNonlinfit_getChi2Detail( Chi2Detail:fVector );
procedure MF_multiNonlinfit_getBestValues( BestValues: fVector );
function MF_multiNonlinfit_getTestDir: Integer;
function MF_multiNonlinfit_getTestPar: UInt;
function MF_multiNonlinfit_getTestRun: UInt;
procedure MF_multiNonlinfit_stop;
(identical syntax for the MF_multiNonlinfitwW_... functions) |
|
Description | MF_multiNonlinfit_autoDeriv performs a numerical differentiation of a user-provided z=f(x,y) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to MF_multiNonlinfit. The model function that is differentiated by MF_multiNonlinfit_autoDeriv is the one passed in the same call to MF_multiNonlinfit (see that function for details!).
The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function.
MF_multiNonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before MF_multiNonlinfit has had the chance to calculate c2, MF_multiNonlinfit_getChi2 returns -1.0.
MF_multiNonlinfit_getChi2Detail fills the user-supplied vector Chi2Detail with the individual figures-of-merit (c2iex or, for robust fits, |ciex|) for all experiments. The sum over these individual c2iex or |ciex| values is the best c2 (or |c|) obtained so far, as returned by MF_multiNonlinfit_getChi2.
MF_multiNonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest.
MF_multiNonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions).
MF_multiNonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation.
MF_multiNonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first.
MF_multiNonlinfit_stop makes MF_multiNonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data. |
|
|
MCF_mulV |
MCD_mulV |
MCE_mulV |
|
Function | multiply a matrix by a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_mulV( fVector Y, fMatrix A, fVector X, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::mulV( const matrix<T>& MA, const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_mulV( Y:fVector; MA:fMatrix; X:fVector; htA, lenA:UInt ); |
|
Description | Y = MA * X
the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = lenA, sizY = htA.
|
|
|
|
|
Syntax C/C++ | #include <MFstd.h>
void MF_neg( fMatrix B, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::neg( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_neg( MB, MA:fMatrix; ht, len:UInt ); |
|
Description | MBi,j = -MAi,j |
|
|
|
Function | de-allocate a certain number of matrices (C/C++ only) |
|
Syntax C/C++ | #include <MFstd.h>
void M_nfree( unsigned numfree, ... ); |
Pascal/Delphi | This function does not exist |
|
Description | The parameter numfree "tells" the function how many matrices it has to free. These matrices follow in the parameter list after numfree. De-allocation of matrices not allocated by one of the functions of the MF_matrix or MF_matrix0 family is not possible.
Pascal/Delphi: since a variable number of parameters is not supported in Pascal language, this function is missing.
|
Example C/C++ | M_nfree( 3, MX, MY, MZ ); |
|
|
VF_nonlinfit
| VD_nonlinfit |
VE_nonlinfit |
VF_nonlinfitwW |
VD_nonlinfitwW |
VE_nonlinfitwW |
|
Function | fit y=f(x) data to a model-function which may be nonlinear in its parameters |
|
Syntax C/C++ | #include <MFstd.h>
float VF_nonlinfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, ui sizex,
void modelfunc(fVector YModel, fVector XModel, ui size),
void derivatives(fVector dYdAi, fVector X, ui size, unsigned iPar) );
float VF_nonlinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fVector InvVar, ui sizex,
void modelfunc(fVector YModel, fVector X, ui size),
void derivatives(fVector dYdAi, fVector X, ui size, unsigned i) ); |
void VF_linfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, ui sizex,
void funcs(fVector BasFuncs, float x, unsigned nfuncs));
void VF_linfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fVector InvVar, ui sizex,
void funcs(fVector BasFuncs, float x, unsigned nfuncs));
C++ MatObj | #include <OptiVec.h>
void vector<T>::nonlinfit( const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y,
void modelfunc(fVector YModel, fVector XModel, ui size),
void derivatives(fVector dYdAi, fVector X, ui size, unsigned iPar) );
void vector<T>::nonlinfitwW( matrix<T> Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const vector<T>& InvVar,
void modelfunc(fVector YModel, fVector XModel, ui size),
void derivatives(fVector dYdAi, fVector X, ui size, unsigned iPar) );
void vector<T>::nonlinfitwW( matrix<T>* Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const vector<T>& InvVar,
void modelfunc(fVector YModel, fVector XModel, ui size),
void derivatives(fVector dYdAi, fVector X, ui size, unsigned iPar) ); |
Pascal/Delphi | uses VFnlfit;
function VF_nonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; X, Y: fVector; sizex: UInt; ModelFunc, Derivatives: Pointer ): Single;
function VF_nonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; X, Y, InvVar:fVector; sizex: UInt; ModelFunc, Derivatives: Pointer ): Single; |
|
Description | The input data X, Y (and InvVar) are used to evaluate the parameter array A with npars elements ai of an arbitrary model function y = f(x).
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
X, Y, InvVar | vectors of size sizex, holding the input data |
modelfunc | user-defined model function |
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters |
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling VF_nonlinfit. The better your initial guess of the parameters, the faster VF_nonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!).
You must provide a model function "modelfunc" which, for a given vector of x-values, must calculate the corresponding "theoretical" y-values. In C/C++, it has to be defined as
| Model function for C/C++ |
void _cdecl MyFunc( fVector Y, fVector X, ui size )
{
for (ui i=0; i<size; i++ )
Y[i] = f( X[i] );
}
f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS).
In addition to the model function, VF_nonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for C/C++ |
void _cdecl MyDerivs( fVector dYdAi, fVector X, ui size, unsigned ipar )
{
ui i;
switch( ipar )
{
case 0: for(i=0; i<size; i++ )
dYdAi[i] = part_derv_of_Y_w_resp_to_A0( X[i] );
break;
case 1: for(i=0; i<size; i++ )
dYdAi[i] = part_derv_of_Y_w_resp_to_A1( X[i] );
break;
default: /* for all derivatives we don't know: */
VF_nonlinfit_autoDeriv( dYdAi, X, size, ipar);
}
}
A call to VF_nonlinfit will look like:
VF_nonlinfit( A, AStatus, npars, X, Y, sizex, MyFunc, MyDerivs );
In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_nonlinfit with derivaties = NULL:
VF_nonlinfit( A, AStatus, npars, X, Y, sizex, MyFunc, NULL );
| Model function for Pascal/Delphi |
In Pascal/Delphi, the model function has to be defined as
procedure MyFunc( Y, X:fVector; size:UInt );
var i:UInt;
begin
for i:=0 to size-1 do
VF_Pelement( Y, i )^ := f( VF_element( X, i ) );
end;
f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS).
In addition to the model function, VF_nonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for Pascal/Delphi |
procedure MyDerivs( dYdAi, X:fVector; size, ipar:UInt );
var i:UInt;
begin
case ipar of
0: begin
for i:=0 to size-1 do
VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end;
1: begin
for i:=0 to size-1 do
VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end;
else (* for all derivatives we don't know: *)
VF_nonlinfit_autoDeriv( dYdAi, X, size, ipar );
end;
end;
A call to VF_nonlinfit will look like:
VF_nonlinfit( A, AStatus, npars, X, Y, sizex, @MyFunc, @MyDerivs );
Note the address-of operator in front of "MyFunc." and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_nonlinfit with derivaties = nil:
VF_nonlinfit( A, AStatus, npars, X, Y, sizex, @MyFunc, nil );
In the weighted variant, VF_nonlinfitwW, the vector InvVar has to contain the inverse of the variances of the individual X-Y data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
| Both C/C++ and Pascal/Delphi: |
For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of VF_nonlinfit, described here.
|
|
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, VF_nonlinfit and VF_nonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run VF_nonlinfit and VD_nonlinfit in parallel.
These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy. |
|
Error handling | If the number of free parameters (i.e., those with AStatus[i] = 1) exceeds the total number of data points, an error message "Invalid parameter(s)" is generated and the program aborted. |
|
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1 |
|
|
VF_nonlinfit_...
| VD_nonlinfit_... |
VE_nonlinfit_... |
VF_nonlinfitwW_... |
VD_nonlinfitwW_... |
VE_nonlinfitwW_... |
|
|
Syntax C/C++ | #include <MFstd.h>
void VF_nonlinfit_autoDeriv( fVector dYdAi, fVector X, ui size, unsigned ipar );
float VF_nonlinfit_getChi2( void );
void VF_nonlinfit_getBestValues( fVector ABest );
int VF_nonlinfit_getTestDir( void );
unsigned VF_nonlinfit_getTestPar( void );
unsigned VF_nonlinfit_getTestRun( void );
void VF_nonlinfit_stop( void );
(identical syntax for the VF_nonlinfitwW_... functions) |
C++ MatObj | #include <OptiVec.h>
void vector<T>::nonlinfit_getChi2( );
void vector<T>::nonlinfit_getBestValues( );
unsigned vector<T>::nonlinfit_getTestPar( );
unsigned vector<T>::nonlinfit_getTestRun( );
void vector<T>::nonlinfit_stop( );
(identical syntax for the nonlinfitwW_... functions) |
Pascal/Delphi | uses VFnlfit;
procedure VF_nonlinfit_autoDeriv( dYdAi, X: fVector; size, ipar:UInt );
function VF_nonlinfit_getChi2: Single;
procedure VF_nonlinfit_getBestValues( BestValues: fVector );
function VF_nonlinfit_getTestDir: Integer;
function VF_nonlinfit_getTestPar: UInt;
function VF_nonlinfit_getTestRun: UInt;
procedure VF_nonlinfit_stop;
(identical syntax for the VF_nonlinfitwW_... functions) |
|
Description | VF_nonlinfit_autoDeriv performs a numerical differentiation of a user-provided y=f(x) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to VF_nonlinfit. The model function that is differentiated by VF_nonlinfit_autoDeriv is the one passed in the same call to VF_nonlinfit (see that function for details!).
The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function.
VF_nonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before VF_nonlinfit has had the chance to calculate c2, VF_nonlinfit_getChi2 returns -1.0.
VF_nonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest.
VF_nonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions).
VF_nonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation.
VF_nonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first.
VF_nonlinfit_stop makes VF_nonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data. |
|
|
MF_nonlinfit
| MD_nonlinfit |
ME_nonlinfit |
MF_nonlinfitwW |
MD_nonlinfitwW |
ME_nonlinfitwW |
|
Function | fit z=f(x,y) data to a model-function which may be nonlinear in its parameters |
|
Syntax C/C++ | #include <MFstd.h>
float MF_nonlinfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, unsigned htZ, unsigned lenZ,
void modelfunc(fMatrix ZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y ),
void derivatives(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar) );
float MF_nonlinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix Z, fMatrix InvVar, unsigned htZ, unsigned lenZ,
void modelfunc(fMatrix ZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y ),
void derivatives(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar) ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::nonlinfit( const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ,
void modelfunc(fMatrix ZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y ),
void derivatives(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar) );
void vector<T>::nonlinfitwW( matrix<T> Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar,
void modelfunc(fMatrix ZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y ),
void derivatives(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar) );
void vector<T>::nonlinfitwW( matrix<T>* Covar, const vector<int>& AStatus, const vector<T>& X, const vector<T>& Y, const matrix<T>& MZ, const matrix<T>& MInvVar,
void modelfunc(fMatrix ZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y ),
void derivatives(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar) ); |
Pascal/Delphi | uses MFnlfit;
function MF_nonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; X, Y: fVector; MZ: fMatrix; htZ, lenZ: UInt; ModelFunc, Derivatives: Pointer ): Single;
function MF_nonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; X, Y: fVector; MZ, MInvVar: fMatrix; htZ, lenZ: UInt; ModelFunc, Derivatives: Pointer ): Single; |
|
Description | The input data X, Y, MZ (and MInvVar) are used to evaluate the parameter array A with npars elements ai of an arbitrary model function z = f(x,y).
Arguments:
A | vector of size npars; returns the coefficients |
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients |
AStatus | vector of size npars; decides which parameters are treated as free or as fixed |
npars | total number of parameters |
X, Y | vectors of size lenZ and htZ, respectively, spanning the x-y coordinate system of the matrix MZ |
MZ, MInvVar | matrices of dimensions [htZ, lenZ], holding the input data and, in the weighted variant, the inverse of their variances |
modelfunc | user-defined model function |
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters |
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling MF_nonlinfit. The better your initial guess of the parameters, the faster MF_nonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!).
You must provide a model function "modelfunc" which, for given vectors of x and y values, must calculate the corresponding "theoretical" z values. In C/C++, it has to be defined as
| Model function for C/C++ |
void _cdecl MyFunc( fMatrix Z, unsigned htZ, unsigned lenZ, fVector X, fVector Y )
{
for (ui i=0; i<htZ; i++ )
for (ui j=0; j<lenZ; j++ )
MZ[i][j] = f( X[j], Y[i] );
}
f( X[j], Y[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS).
In addition to the model function, MF_nonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for C/C++ |
void _cdecl MyDerivs( fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar )
{
ui i;
switch( ipar )
{
case 0:
for(i=0; i<htZ; i++ )
for( j=0; j<lenZ; j++ )
dZdAi[i][j] = part_derv_MZ_w_resp_to_A0( X[j], Y[i] );
break;
case 1:
for(i=0; i<htZ; i++ )
for( j=0; j<lenZ; j++ )
dZdAi[i][j] = part_derv_MZ_w_resp_to_A1( X[j], Y[i] );
break;
default: /* for all derivatives we don't know: */
MF_nonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar);
}
}
A call to MF_nonlinfit will look like:
MF_nonlinfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, MyFunc, MyDerivs );
In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_nonlinfit with derivaties = NULL:
MF_nonlinfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, MyFunc, NULL );
| Model function for Pascal/Delphi |
In Pascal/Delphi, the model function has to be defined as
procedure MyFunc( MZ:fMatrix; htZ, lenZ:UInt; X, Y:fVector );
var i, j:UInt;
begin
for i:=0 to htZ-1 do
for j:=0 to lenZ-1 do
MF_Pelement( MZ, htZ, lenZ, i, j )^ :=
f( VF_element( X, j ), VF_element( Y, i ) );
end;
f( Xj, Yi ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS).
In addition to the model function, MF_nonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
| Partial derivatives coded for Pascal/Delphi |
procedure MyDerivs( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar:UInt );
var i, j:UInt;
begin
case ipar of
0: begin
for i:=0 to htZ-1 do
for j:=0 to lenZ-1 do
MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A0(VF_element( X, j ), VF_element( Y, i ));
end;
1: begin
for i:=0 to htZ-1 do
for j:=0 to lenZ-1 do
MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A1(VF_element( X, j ), VF_element( Y, i ));
end;
else (* for all derivatives we don't know: *)
MF_nonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar );
end;
end;
A call to MF_nonlinfit will look like:
MF_nonlinfit( A, AStatus, npars, MZ, htZ, lenZ, X, Y, @MyFunc, @MyDerivs );
Note the address-of operator in front of "MyFunc." and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_nonlinfit with derivaties = nil:
MF_nonlinfit( A, AStatus, npars, MZ, htZ, lenZ, X, Y, @MyFunc, nil );
In the weighted variant, MF_nonlinfitwW, the matrix MInvVar has to contain the inverse of the variances of the individual X-Y-Z data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
| Both C/C++ and Pascal/Delphi: |
For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of MF_nonlinfit, described here.
|
|
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, MF_nonlinfit and MF_nonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run MF_nonlinfit and MD_nonlinfit in parallel.
These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy. |
|
Error handling | If the number of free parameters (i.e., those with AStatus[i] = 1) exceeds the total number of data points, an error message "Invalid parameter(s)" is generated and the program aborted. |
|
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1 |
|
|
MF_nonlinfit_...
| MD_nonlinfit_... |
ME_nonlinfit_... |
MF_nonlinfitwW_... |
MD_nonlinfitwW_... |
ME_nonlinfitwW_... |
|
|
Syntax C/C++ | #include <MFstd.h>
void MF_nonlinfit_autoDeriv( fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar );
float MF_nonlinfit_getChi2( void );
void MF_nonlinfit_getBestValues( fVector ABest );
unsigned MF_nonlinfit_getTestRun( void );
unsigned MF_nonlinfit_getTestPar( void );
int MF_nonlinfit_getTestDir( void );
void MF_nonlinfit_stop( void );
(identical syntax for the MF_nonlinfitwW_... functions) |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::nonlinfit_getChi2( );
void vector<T>::Mnonlinfit_getBestValues( );
unsigned matrix<T>::nonlinfit_getTestPar( );
unsigned matrix<T>::nonlinfit_getTestRun( );
void matrix<T>::nonlinfit_stop( );
(identical syntax for the nonlinfitwW_... functions) |
Pascal/Delphi | uses MFnlfit;
procedure MF_nonlinfit_autoDeriv( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar: UInt );
function MF_nonlinfit_getChi2: Single;
procedure MF_nonlinfit_getBestValues( BestValues: fVector );
function MF_nonlinfit_getTestRun: UInt;
function MF_nonlinfit_getTestPar: UInt;
function MF_nonlinfit_getTestDir: Integer;
procedure MF_nonlinfit_stop;
(identical syntax for the MF_nonlinfitwW_... functions) |
|
Description | MF_nonlinfit_autoDeriv performs a numerical differentiation of a user-provided z=f(x,y) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to MF_nonlinfit. The model function that is differentiated by MF_nonlinfit_autoDeriv is the one passed in the same call to MF_nonlinfit (see that function for details!).
The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function.
MF_nonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before MF_nonlinfit has had the chance to calculate c2, MF_nonlinfit_getChi2 returns -1.0.
MF_nonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest.
MF_nonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions).
MF_nonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation.
MF_nonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first.
MF_nonlinfit_stop makes MF_nonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data. |
|
|
MF_outerprod
| MD_outerprod |
ME_outerprod |
MCF_outerprod |
MCD_outerprod |
MCE_outerprod |
|
Function | formation of a matrix by the "outer product" of two vectors |
|
Syntax C/C++ | #include <MFstd.h>
void MF_outerprod( fMatrix A, fVector X, fVector Y, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::outerprod( const vector<T>& X, const vector<T>& Y ); |
Pascal/Delphi | uses MFstd;
procedure MF_outerprod( MA:fMatrix; X, Y:fVector; ht, len:UInt ); |
|
Description | MAi,j = Xi * Yj |
|
|
MF_Parzen
| MD_Parzen |
ME_Parzen |
|
Function | two-dimensional Parzen window for spatial frequency analysis |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Parzen( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Parzen( ); |
Pascal/Delphi | uses MFstd;
procedure MF_Parzen( MA:fMatrix; ht, len:UInt ); |
|
Description | MAi,j = (1 - |(i - 0.5*(ht - 1)) / 0.5*(ht + 1)|) * (1 - |(j - 0.5*(len - 1)) / 0.5*(len + 1)|) |
|
|
MF_Pelement
| MD_Pelement |
ME_Pelement |
MCF_Pelement |
MCD_Pelement |
MCE_Pelement |
|
Function | get pointer to a matrix element |
|
Syntax C/C++ | #include <MFstd.h>
float * MF_Pelement( fMatrix X, unsigned ht, unsigned len, unsigned m, unsigned n ); |
C++ MatObj | #include <OptiVec.h>
T * matrix<T>::Pelement( const unsigned m, const unsigned n ); |
Pascal/Delphi | uses MFstd;
function MF_Pelement( MA:fMatrix; ht, len, m, n:UInt ): PSingle; |
|
Description | A pointer to the element MAm,n is returned.
This function is needed to access elements of dynamically allocated matrices, for which older versions of Borland C++ had a pointer arithmetics bug, and Pascal/Delphi - unlike C - does not provide an own mechanism at all. Writing a matrix element through this function, use the dereferenced-pointer syntax: |
C/C++ | *MF_Pelement( MA, ht, len, m, n ) = 3.5; |
Pascal/Delphi | MF_Pelement( MA, ht, len, m, n )^ := 3.5;
Read-only access to matrix elements is provided by the related function, MF_element |
|
Return value | pointer to the matrix element MAm,n |
|
|
VF_polyfit
| VD_polyfit |
VE_polyfit |
VF_polyfitwW |
VD_polyfitwW |
VE_polyfitwW |
|
Function | fitting of one X-Y data set to a polynomial |
|
Syntax C/C++ | #include <MFstd.h>
void VF_polyfit( fVector A, unsigned deg, fVector X, fVector Y, ui sizex );
void VF_polyfitwW( fVector A, fMatrix Covar, unsigned deg, fVector X, fVector Y, fVector InvVar, ui sizex ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::polyfit( const vector<T>& X, const vector<T>& Y );
void vector<T>::polyfitwW( matrix<T> Covar, const vector<T>& X, const vector<T>& Y, const vector<T>& InvVar );
void vector<T>::polyfitwW( matrix<T>* Covar, const vector<T>& X, const vector<T>& Y, const vector<T>& InvVar ); |
Pascal/Delphi | uses MFstd;
procedure VF_polyfit( A:fVector; deg:UInt; X, Y:fVector; sizex:UInt );
procedure VF_polyfitwW( A:fVector; Covar:fMatrix; deg:UInt; X, Y, InvVar:fVector; sizex:UInt ); |
|
Description | The input data are used to determine the coefficients ai of a polynomial
Pi = a0 + a1Xi + a2Xi2 ... anXin
so as to minimize the deviation between the "theoretical" Pi values, calculated by the polynomial, and the actual Yi values. To be more precise, the figure-of-merit chi-square,
c2 = sum( 1/si2 * (Pi - Yi)2 )
is minimized. In the weighted variant, VF_polyfitwW, 1/si2 has to be provided as the vector InvVar. In the non-weighted variant, all si are assumed as 1.0.
Arguments:
A | vector of size deg+1; returns the coefficients |
Covar | matrix of dimensions [deg+1, deg+1]; returns the covariances of the coefficients |
deg | the degree of the fitting polynomial |
X, Y, InvVar | vectors of size sizex, holding the input data |
|
|
|
MF_print
| MD_print |
ME_print |
MCF_print |
MCD_print |
MCE_print |
|
Function | print a matrix in ASCII format to stdout, assuming a linewidth of 80 characters (DOS and 16-bit Windows with EasyWin only) |
|
Syntax C/C++ | #include <MFstd.h>
void MF_print( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::print(); |
Pascal/Delphi | uses MFstd;
procedure MF_print( MA:fMatrix; ht, len:UInt ); |
|
Description | The matrix MA is written to stream. Each line corresponds to one row of the matrix. The lines are numbered. The linewidth is assumed to be 80 characters. If this linewidth is too small to write all columns, rows are cut off.
Cartesian complex numbers are printed in braces, with the real and imaginary parts separated by a komma: {Re, Im}.
In contrast to MF_write, it is not possible to override the automatic choice of the format used for printing. The number of digits per element is determined by the available space, which depends in turn on the parameter len.
In contrast to MF_cprint, no paging is performed.
This family of functions is available under Windows only in connection with EasyWin, and should not be used within TurboVision programs. |
|
|
MF_random
| MD_random |
ME_random |
MCF_random |
MCD_random |
MCE_random |
|
Function | fill a matrix with high-quality random numbers |
|
Syntax C/C++ | #include <MFstd.h>
long MF_random( fMatrix A, unsigned ht, unsigned len, long seed, float MinVal, float MaxVal ); |
C++ MatObj | #include <OptiVec.h>
long matrix<T>::random( const long& seed, const T& MinVal, const T& MaxVal ); |
Pascal/Delphi | uses MFstd;
function MF_random( MA:fMatrix; ht, len:UInt; seed:LongInt; MinVal, MaxVal:Single ): LongInt; |
|
Description | The matrix MA is filled with random numbers. Within the ranges defined by MinVal and MaxVal, and within the restrictions of floating-point representation, all numbers are equally probable (including the extreme values themselves), i.e., so-called "uniform deviates" are produced. The parameter seed may be any number. Successive calls to one and the same of these functions will yield identical sequences, if seed is chosen equal; if seed is chosen differently for successive calls, the results will be uncorrelated.
Internally, these functions employ a 32-bit integer random number generator by H.W.Lewis, with additional steps (so-called "Bays-Durham shuffle") to break sequential correlations. This ensures very good randomness, far superior to simpler generators (like the rand function of C/C++ compilers or the random function of Pascal/Delphi).
A long value is returned which may be used as new seed for subsequent calls. |
|
|
Return value | last 32-bit random number generated; this may be used as a new seed value for future calls. |
|
|
MCF_read |
MCD_read |
MCE_read |
|
Function | read a matrix in ASCII format from a stream |
|
Syntax C/C++ | #include <MFstd.h>
void MF_read( fMatrix A, unsigned ht, unsigned len, FILE *stream ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::read( FILE *stream ); |
Pascal/Delphi | uses MFstd;
{Delphi version:}
procedure MF_read( MA:fMatrix; ht, len:UInt; var Stream:TextFile );
{Turbo Pascal version:}
procedure MF_read( MA:fMatrix; ht, len:UInt; var Stream:Text ); |
|
Description | The matrix MA of ht*len elements is read in ASCII format from stream. Normally, this function will be used to import matrices from a program which cannot store numbers in machine format. It can also be used to retrieve matrices previously stored by MF_write. For storing and retrieving intermediate results, however, the function pair MF_store / MF_recall is to be preferred over MF_write / MF_read (see MF_write).
Cartesian complex versions:
Real und imaginary parts may, but need not, be enclosed in braces { } or brackets ( ). However, you must be consequent: Either all or no element may be written with braces or brackets.
A komma may (but need not) separate the two parts. The imaginary part must always be explicitly specified, even if it is zero.
Examples for legal formats are:
0.3 0.5 (neither braces nor separating komma)
0.3, 0.5 (no braces; separating komma)
{0.3 0.5} (braces; no separating komma)
(0.3, 0.5) (brackets and separating komma)
|
C/C++ specific: | The entries to be read must be separated by whitespace (' ', '\n', or '\t'). Additionally, one (!) "non-whitespace" character is tolerated after each entry, if it follows directly after the last digit. After it, there must be one or more whitespace characters.
|
Pascal/Delphi specific: | The entries to be read must be separated by whitespace (' ', #13, or #9).
Whereas the C/C++ version of these functions follows the conventions of the C functions strtod, strtol, etc., the Pascal/Delphi version has to follow the rules applying to the Pascal/Delphi function Read. This makes the Pascal/Delphi version much less flexible than the C version:
- no separation characters allowed other than ' ' and #9,
- no automatic truncation of overflowing numbers |
|
Error handling | C/C++:
Overflowing numbers are silently truncated to ±HUGE_VAL.
Pascal/Delphi:
Overflowing numbers or numbers otherwise not conforming to the format requirements lead to an I/O error. |
|
|
MF_recall
| MD_recall |
ME_recall |
MCF_recall |
MCD_recall |
MCE_recall |
|
Function | Read a matrix in binary format from a stream |
|
Syntax C/C++ | #include <MFstd.h>
void MF_recall( fMatrix A, unsigned ht, unsigned len, FILE *stream); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::recall( FILE *stream ); |
Pascal/Delphi | uses MFstd;
procedure MF_recall( MA:fMatrix; ht, len:UInt; var Stream:FILE ); |
|
Description | The matrix MA of ht*len elements is read from stream in binary format. Normally, these functions are used to retrieve data stored by the respective function of the MF_store family.
In C/C++, matrices are stored by rows, where as Pascal/Delphi and Fortran work with matrices stored by columns. This means that you will get the transpose of a matrix stored by a C/C++ program, if you read it with a Pascal/Delphi program, and vice versa. In this case, simply call
MF_transpose( MA, MA, ht, len );. |
|
|
MF_Row_addC
| MD_Row_addC |
ME_Row_addC |
MCF_Row_addC |
MCD_Row_addC |
MCE_Row_addC |
|
Function | add a constant to all elements of one row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_addC( fMatrix A, unsigned ht, unsigned len, unsigned iRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_addC( const unsigned iRow, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_addC( MA:fMatrix; ht, len, iRow:UInt; C:Single ); |
|
Description | MAiRow,i += C, i=0,...,len-1 |
|
|
MF_Row_addV
| MD_Row_addV |
ME_Row_addV |
MCF_Row_addV |
MCD_Row_addV |
MCE_Row_addV |
|
Function | element-wise addition of one row and a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_addV( fMatrix A, unsigned ht, unsigned len, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_addV( const unsigned iRow, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_addV( MA:fMatrix; ht, len, iRow:UInt; X:fVector ); |
|
Description | MAiRow,i += Xi, i=0,...,len-1 |
|
|
MF_Row_delete
| MD_Row_delete |
ME_Row_delete |
MCF_Row_delete |
MCD_Row_delete |
MCE_Row_delete |
|
Function | delete one row from a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_delete( fMatrix B, fMatrix A, unsigned htA, unsigned lenA, unsigned iRow ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_delete( const matrix<T>& MA, const unsigned iRow ); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_delete( MB, MA:fMatrix; htA, lenA, iRow:UInt ); |
|
Description | MBi,j = MAi,j, i=0,...,iRow-1, j=0,...,len-1
MBi,j = MAi+1,j, i=iRow,...,htA-2, j=0,...,lenA-1
The parameters htA and lenA refer to the input matrix |
|
|
MF_Row_divC
| MD_Row_divC |
ME_Row_divC |
MCF_Row_divC |
MCD_Row_divC |
MCE_Row_divC |
|
Function | divide all elements of one row by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_divC( fMatrix A, unsigned ht, unsigned len, unsigned iRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_divC( const unsigned iRow, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_divC( MA:fMatrix; ht, len, iRow:UInt; C:Single ); |
|
Description | MAiRow,i /= C, i=0,...,len-1 |
|
|
MF_Row_divrC
| MD_Row_divrC |
ME_Row_divrC |
MCF_Row_divrC |
MCD_Row_divrC |
MCE_Row_divrC |
|
Function | reverse division: divide a constant by all elements of one row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_divrC( fMatrix A, unsigned ht, unsigned len, unsigned iRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_divrC( const unsigned iRow, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_divrC( MA:fMatrix; ht, len, iRow:UInt; C:Single ); |
|
Description | MAiRow,i = C / MAiRow,i, i=0,...,len-1 |
|
|
MF_Row_divrV
| MD_Row_divrV |
ME_Row_divrV |
MCF_Row_divrV |
MCD_Row_divrV |
MCE_Row_divrV |
|
Function | element-wise reverse division: divide a vector by one row of a matrix, storing the result back into the row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_divrV( fMatrix A, unsigned ht, unsigned len, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_divrV( const unsigned iRow, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_divrV( MA:fMatrix; ht, len, iRow:UInt; X:fVector ); |
|
Description | MAiRow,i = Xi / MAiRow,i, i=0,...,len-1 |
|
|
MF_Row_divV
| MD_Row_divV |
ME_Row_divV |
MCF_Row_divV |
MCD_Row_divV |
MCE_Row_divV |
|
Function | element-wise division of one row of a matrix by a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_divV( fMatrix A, unsigned ht, unsigned len, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_divV( const unsigned iRow, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_divV( MA:fMatrix; ht, len, iRow:UInt; X:fVector ); |
|
Description | MAiRow,i /= Xi, i=0,...,len-1 |
|
|
MF_Row_equ0
| MD_Row_equ0 |
ME_Row_equ0 |
MCF_Row_equ0 |
MCD_Row_equ0 |
MCE_Row_equ0 |
|
Function | initialize all elements of one row with zero |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_equ0( fMatrix A, unsigned ht, unsigned len, unsigned iRow ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_equ0( const unsigned iRow ); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_equ0( MA:fMatrix; ht, len, iRow:UInt ); |
|
Description | MAiRow,i = 0, i=0,...,len-1 |
|
|
MF_Row_equC
| MD_Row_equC |
ME_Row_equC |
MCF_Row_equC |
MCD_Row_equC |
MCE_Row_equC |
|
Function | initialize all elements of one row with a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_equC( fMatrix A, unsigned ht, unsigned len, unsigned iRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_equC( const unsigned iRow, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_equC( MA:fMatrix; ht, len, iRow:UInt; C:Single ); |
|
Description | MAiRow,i = C, i=0,...,len-1 |
|
|
MF_Row_equV
| MD_Row_equV |
ME_Row_equV |
MCF_Row_equV |
MCD_Row_equV |
MCE_Row_equV |
|
Function | copy a vector into one row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_equV( fMatrix A, unsigned ht, unsigned len, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_equV( const unsigned iRow, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_equV( MA:fMatrix; ht, len, iRow:UInt; X:fVector ); |
|
Description | MAiRow,i = Xi, i=0,...,len-1 |
|
|
MF_Row_extract
| MD_Row_extract |
ME_Row_extract |
MCF_Row_extract |
MCD_Row_extract |
MCE_Row_extract |
|
Function | copy one row into a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_extract( fVector Y, fMatrix A, unsigned ht, unsigned len, unsigned iRow ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Row_extract( const matrix<T>& MA, const unsigned iRow ); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_extract( Y:fVector; MA:fMatrix; ht, len, iRow:UInt ); |
|
Description | Xi = MAiRow,i, i=0,...,len-1 |
|
|
MF_Row_insert
| MD_Row_insert |
ME_Row_insert |
MCF_Row_insert |
MCD_Row_insert |
MCE_Row_insert |
|
Function | augment a matrix by insertion of one row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_insert( fMatrix B, fMatrix A, unsigned htB, unsigned lenB, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_insert( const matrix<T>& MA, const unsigned iRow, const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_insert( MB, MA:fMatrix; htB, lenB, iRow:UInt; X:fVector ); |
|
Description | MBi,j = MAi,j, i=0,...,iRow-1, j=0,...,len-1
MBiRow,j = Xj, j=0,...,lenB-1
MBi,j = MAi-1,j, i=iRow,...,htB-1, j=0,...,lenB-1
The parameters htB and lenB refer to the output matrix |
|
|
MF_Row_mulC
| MD_Row_mulC |
ME_Row_mulC |
MCF_Row_mulC |
MCD_Row_mulC |
MCE_Row_mulC |
|
Function | multiply all elements of one row by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_mulC( fMatrix A, unsigned ht, unsigned len, unsigned iRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_mulC( const unsigned iRow, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_mulC( MA:fMatrix; ht, len, iRow:UInt; C:Single ); |
|
Description | MAiRow,i *= C, i=0,...,len-1 |
|
|
MF_Row_mulV
| MD_Row_mulV |
ME_Row_mulV |
MCF_Row_mulV |
MCD_Row_mulV |
MCE_Row_mulV |
|
Function | element-wise multiplication of one row and a vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_mulV( fMatrix A, unsigned ht, unsigned len, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_mulV( const unsigned iRow, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_mulV( MA:fMatrix; ht, len, iRow:UInt; X:fVector ); |
|
Description | MAiRow,i *= Xi, i=0,...,len-1 |
|
|
MF_Row_subC
| MD_Row_subC |
ME_Row_subC |
MCF_Row_subC |
MCD_Row_subC |
MCE_Row_subC |
|
Function | subtract a constant from all elements of one row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_subC( fMatrix A, unsigned ht, unsigned len, unsigned iRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_subC( const unsigned iRow, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_subC( MA:fMatrix; ht, len, iRow:UInt; C:Single ); |
|
Description | MAiRow,i -= C, i=0,...,len-1 |
|
|
MF_Row_subrC
| MD_Row_subrC |
ME_Row_subrC |
MCF_Row_subrC |
MCD_Row_subrC |
MCE_Row_subrC |
|
Function | reverse subtraction: a constant minus one row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_subrC( fMatrix A, unsigned ht, unsigned len, unsigned iRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_subrC( const unsigned iRow, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_subrC( MA:fMatrix; ht, len, iRow:UInt; C:Single ); |
|
Description | MAiRow,i = C - MAiRow,i, i=0,...,len-1 |
|
|
MF_Row_subrV
| MD_Row_subrV |
ME_Row_subrV |
MCF_Row_subrV |
MCD_Row_subrV |
MCE_Row_subrV |
|
Function | element-wise reverse subtraction: subtract one row from a vector, storing the result back into the row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_subrV( fMatrix A, unsigned ht, unsigned len, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_subrV( const unsigned iRow, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_subrV( MA:fMatrix; ht, len, iRow:UInt; X:fVector ); |
|
Description | MAiRow,i = Xi - MAiRow,i, i=0,...,len-1 |
|
|
MF_Row_subV
| MD_Row_subV |
ME_Row_subV |
MCF_Row_subV |
MCD_Row_subV |
MCE_Row_subV |
|
Function | element-wise subtraction of a vector from one row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Row_subV( fMatrix A, unsigned ht, unsigned len, unsigned iRow, fVector X ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Row_subrV( const unsigned iRow, const vector<T>& X); |
Pascal/Delphi | uses MFstd;
procedure MF_Row_subV( MA:fMatrix; ht, len, iRow:UInt; X:fVector ); |
|
Description | MAiRow,i -= Xi, i=0,...,len-1 |
|
|
MF_Rows_absmax
| MD_Rows_absmax |
ME_Rows_absmax |
MCF_Rows_absmax |
MCD_Rows_absmax |
MCE_Rows_absmax |
|
Function | store the absolute maxima of all individual rows in a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_absmax( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Rows_absmax( const matrix<T>& MA );
void vector<T>::Rows_absmax( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_absmax( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | The maximum absolute value of each row i is stored as the element Yi for i=0,...,ht-1 |
|
|
MCF_Rows_absmaxReIm
| MCD_Rows_absmaxReIm |
MCE_Rows_absmaxReIm |
|
Function | Separate determination of the largest absolute values of the real and imaginary parts of each row |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Rows_absmaxReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Rows_absmaxReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Rows_absmaxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The maximum absolute values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1 |
|
|
MF_Rows_absmin
| MD_Rows_absmin |
ME_Rows_absmin |
MCF_Rows_absmin |
MCD_Rows_absmin |
MCE_Rows_absmin |
|
Function | store the absolute minima of all individual rows in a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_absmin( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Rows_absmin( const matrix<T>& MA );
void vector<T>::Rows_absmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_absmin( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | The minimum absolute value of each row i is stored as the element Yi for i=0,...,ht-1 |
|
|
MCF_Rows_absminReIm
| MCD_Rows_absminReIm |
MCE_Rows_absminReIm |
|
Function | Separate determination of the largest absolute values of the real and imaginary parts of each row |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Rows_absminReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Rows_absminReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Rows_absminReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The maximum absolute values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1 |
|
|
MF_Rows_add
| MD_Rows_add |
ME_Rows_add |
MCF_Rows_add |
MCD_Rows_add |
MCE_Rows_add |
|
Function | make one row the sum of itself and another row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_add( fMatrix A, unsigned ht, unsigned len, unsigned destRow, unsigned sourceRow ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_add( const unsigned destRow, const unsigned sourceRow ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_add( MA:fMatrix; ht, len, destRow, sourceRow:UInt ); |
|
Description | MAdestRow, j += MAsourceRow, j, i=0,...,len-1 |
|
|
MCF_Rows_cabsmax
| MCD_Rows_cabsmax |
MCE_Rows_cabsmax |
|
Function | Find the complex numbers of largest magnitude along rows and store them in a column vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Rows_cabsmax( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Rows_cabsmax( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Rows_cabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each row i of MA, the complex number of largest magnitude, sqrt(Re2+Im2), is found and stored as the element Yi for i=0,..,ht-1 |
|
|
MCF_Rows_cabsmin
| MCD_Rows_cabsmin |
MCE_Rows_cabsmin |
|
Function | Find the complex numbers of smallest magnitude along rows and store them in a column vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Rows_cabsmin( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Rows_cabsmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Rows_cabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each row i of MA, the complex number of smallest magnitude, sqrt(Re2+Im2), is found and stored as the element Yi for i=0,..,ht-1 |
|
|
MF_Rows_Cadd
| MD_Rows_Cadd |
ME_Rows_Cadd |
MCF_Rows_Cadd |
MCD_Rows_Cadd |
MCE_Rows_Cadd |
|
Function | make one row the sum of itself and another row, scaled by a constant |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_Cadd( fMatrix A, unsigned ht, unsigned len, unsigned destRow, unsigned sourceRow, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_Cadd( const unsigned destRow, const unsigned sourceRow, const T& C ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_Cadd( MA:fMatrix; ht, len, destRow, sourceRow:UInt; C:Single ); |
|
Description | MAdestRow, j += C * MAsourceRow, j, i=0,...,len-1 |
|
|
MF_Rows_exchange
| MD_Rows_exchange |
ME_Rows_exchange |
MCF_Rows_exchange |
MCD_Rows_exchange |
MCE_Rows_exchange |
|
Function | exchange two rows |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_exchange( fMatrix A, unsigned ht, unsigned len, unsigned i1, unsigned i2 ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_exchange( const unsigned i1, const unsigned i2 ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_exchange( MA:fMatrix; ht, len, i1, i2:UInt ); |
|
Description | The elements of the rows i1 and i2 are exchanged. |
|
|
MF_Rows_lincomb
| MD_Rows_lincomb |
ME_Rows_lincomb |
MCF_Rows_lincomb |
MCD_Rows_lincomb |
MCE_Rows_lincomb |
|
Function | linear combination of two rows |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_lincomb( fMatrix A, unsigned ht, unsigned len, unsigned destRow, float destC, unsigned srceRow, float srceC ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_lincomb( const unsigned destRow, const T& destC, const unsigned sourceRow, const T& srceC ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_lincomb( MA:fMatrix; ht, len:UInt; destRow:UInt; destC:Single;
srceRow:Uint; srceC:Single ); |
|
Description | MAdestRow, j = destC * MAdestRow, j+ srceC * MAsrceRow, j, j=0,...,len-1 |
|
|
MF_Rows_max
| MD_Rows_max |
ME_Rows_max |
MCF_Rows_max |
MCD_Rows_max |
MCE_Rows_max |
|
Function | store the maxima of all individual rows in a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_max( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Rows_max( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_max( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | The maximum value of each row i is stored as the element Yi for i=0,...,ht-1 |
|
|
MCF_Rows_maxReIm
| MCD_Rows_maxReIm |
MCE_Rows_maxReIm |
|
Function | Separate determination of the largest values of the real and imaginary parts of each row |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Rows_maxReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Rows_maxReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Rows_maxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The maximum values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1 |
|
|
MF_Rows_min
| MD_Rows_min |
ME_Rows_min |
MCF_Rows_min |
MCD_Rows_min |
MCE_Rows_min |
|
Function | store the minima of all individual rows in a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_min( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Rows_min( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_min( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | The smallest or most negative element of each row i is stored as the element Yi for i=0,...,ht-1 |
|
|
MCF_Rows_minReIm
| MCD_Rows_minReIm |
MCE_Rows_minReIm |
|
Function | Separate determination of the smallest values of the real and imaginary parts of each row |
|
Syntax C/C++ | #include <MFstd.h>
void MCF_Rows_minReIm( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> >::Rows_minReIm( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MFstd;
procedure MCF_Rows_minReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | The minimum values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1 |
|
|
MF_Rows_prod
| MD_Rows_prod |
ME_Rows_prod |
MCF_Rows_prod |
MCD_Rows_prod |
MCE_Rows_prod |
|
Function | products over all elements of each individual row, stored in a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_prod(fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Rows_prod( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_prod(Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | Yi = prod( MAi,j, j=0,...,len-1), i=0,...,ht-1 |
|
|
MF_Rows_reflect
| MD_Rows_reflect |
ME_Rows_reflect |
|
Function | Derive the second halves of all rows from their first halves by reflection at the vertical line through the center of the matrix. |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_reflect( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_reflect( ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_reflect( MA:fMatrix; ht, len:UInt ); |
|
Description | MAi, len-j-1 = MAi, j, i=0,...,ht-1; j=0,...,(len-1)/2; |
|
|
MF_Rows_rotate
| MD_Rows_rotate |
ME_Rows_rotate |
MCF_Rows_rotate |
MCD_Rows_rotate |
MCE_Rows_rotate |
|
Function | rotate all rows by a specified number of positions; thereby, whole columns are moved |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_rotate( fMatrix A, unsigned ht, unsigned len, int pos ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_rotate( const int pos ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_rotate( MA:fMatrix; ht, len:UInt; pos:Integer ); |
|
Description | MAi,j = MAi, len-pos+j, j=0,..,pos-1
MAi,j = MAi, j-pos, j=pos,...,len-1 |
|
|
MF_Rows_runprod
| MD_Rows_runprod |
ME_Rows_runprod |
MCF_Rows_runprod |
MCD_Rows_runprod |
MCE_Rows_runprod |
|
Function | running product over row elements |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_runprod( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_runprod( ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_runprod( MA:fMatrix; ht, len:UInt ); |
|
Description | For all rows separately, each element is the product of itself and all preceding elements. This function should be used with care: overflow is easily reached, and underflow may lead to all elements from a certain position on being zero. |
|
|
MF_Rows_runsum
| MD_Rows_runsum |
ME_Rows_runsum |
MCF_Rows_runsum |
MCD_Rows_runsum |
MCE_Rows_runsum |
|
Function | running sum over row elements |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_runsum( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_runsum( ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_runsum( MA:fMatrix; ht, len:UInt ); |
|
Description | For all rows separately, each element is the sum of itself and all preceding elements. |
|
|
MCF_Rows_sabsmax
| MCD_Rows_sabsmax |
MCE_Rows_sabsmax |
|
Function | Find the complex numbers of largest sum |Re| + |Im| along rows and store them in a column vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Rows_sabsmax( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Rows_sabsmax( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Rows_sabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each row i of MA, the complex number with the largest sum, |Re| + |Im|, is found and stored as the element Yi for i=0,..,ht-1 |
|
|
MCF_Rows_sabsmin
| MCD_Rows_sabsmin |
MCE_Rows_sabsmin |
|
Function | Find the complex numbers of largest sum |Re| + |Im| along rows and store them in a column vector |
|
Syntax C/C++ | #include <MCFstd.h>
void MCF_Rows_sabsmin( cfVector Y, cfMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<complex<T> T>::Rows_sabsmin( const matrix<complex<T> >& MA ); |
Pascal/Delphi | uses MCFstd;
procedure MCF_Rows_sabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt ); |
|
Description | Within each row i of MA, the complex number with the largest sum, |Re| + |Im|, is found and stored as the element Yi for i=0,..,ht-1 |
|
|
MF_Rows_sub
| MD_Rows_sub |
ME_Rows_sub |
MCF_Rows_sub |
MCD_Rows_sub |
MCE_Rows_sub |
|
Function | make one row the difference of itself and another row |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_sub( fMatrix A, unsigned ht, unsigned len, unsigned destRow, unsigned sourceRow ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Rows_sub( const unsigned destRow, const unsigned sourceRow ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_sub( MA:fMatrix; ht, len, destRow, sourceRow:UInt; ); |
|
Description | MAdestRow, j -= MAsourceRow, j, i=0,...,len-1 |
|
|
MF_Rows_sum
| MD_Rows_sum |
ME_Rows_sum |
MCF_Rows_sum |
MCD_Rows_sum |
MCE_Rows_sum |
|
Function | sums over all elements of each individual row, stored in a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Rows_sum( fVector Y, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::Rows_sum( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Rows_sum( Y:fVector; MA:fMatrix; ht, len:UInt ); |
|
Description | Yi = sum( MAi,j, j=0,...,len-1), i=0,...,ht-1 |
|
|
MF_safeSolve
| MD_safeSolve |
ME_safeSolve |
|
Function | solve a linear system MA * X = B; in case the system is singular, get one solution out of the infinite solution space |
|
Syntax C/C++ | #include <MFstd.h>
int MF_safeSolve( fVector X, fMatrix A, fVector B, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::safeSolve( const matrix<T>& MA, const vector<T>& B ); |
Pascal/Delphi | uses MFstd;
function MF_safeSolve( X:fVector; MA:fMatrix; B:fVector; len:UInt ):Integer; |
|
Description | MF_safeSolve is similar to MF_solve with the difference that, in case there is no unique solution of the linear system (i.e., LU decomposition fails), singular value decomposition is employed to obtain at least one solution out of the infinite solution space. Recall that the problem with singular linear systems is not that they don't have a solution, but rather that they are under-determined and have infinitely many solutions. In other words, one or more elements of the solution vector can be chosen arbitrarily. This is what MF_safeSolve does, with the additional constraint that the "smallest" solution vector in the least-squares sense is determined.
A return value of 0 indicates success via LUD, 1 signals success via SVD, and -1 is returned in the very rare case that even SVD fails. |
|
|
|
Function | Calculate a color scale for color density plots |
|
Syntax C/C++ | #include <Mgraph.h>
void M_setDensityBounds( extended zmin, extended zmax, COLORREF mincolor, COLORREF maxcolor ); |
Pascal/Delphi | uses Mgraph;
procedure M_setDensityBounds( zmin, zmax: Extended; mincolor, maxcolor: COLORREF ); |
|
Description | A color scale is calculated between the colors mincolor and maxcolor, corresponding to zmin and zmax. In any following MF_xyzDataDensityMap or MF_zDataDensityMap plot, the z values will be translated into colors by interpolation between the extreme values set by M_setDensityBounds. You will rarely call this function directly. It is internally called by all functions of the MF_xyzAutoDensityMap and MF_zAutoDensityMap families. |
|
|
|
Function | Set a color scale and draw an X-Y coordinate system for matrix color-density plots |
|
Syntax C/C++ | #include <Mgraph.h>
void M_setDensityMapBounds( extended xmin, extended xmax, extended ymin, extended ymax, extended zmin, extended zmax, COLORREF mincolor, COLORREF maxcolor ); |
Pascal/Delphi | uses Mgraph;
procedure M_setDensityMapBounds( xmin, xmax, ymin, ymax, zmin, zmax: Extended; mincolor, maxcolor: COLORREF ); |
|
Description | Similarly to the function V_drawAxes for X-Y vector plots, this function calculates a color scale from the parameters mincolor, maxcolor, zmin and zmax, and prepares an X-Y coordinate system with the x and y ranges specified by xmin, xmax, ymin, and ymax for color-density plots of matrices. Unlike M_findDensityMapBounds, no adjustment of the x and y ranges is made.
The user will rarely call this function himself. It is internally called by all functions of the MF_xyzAutoDensityMap and MF_zAutoDensityMap families. |
|
|
VF_setLinfitNeglect
| VD_setLinfitNeglect |
VE_setLinfitNeglect |
|
Function | define significance threshold for data fitting to linear models |
|
Syntax C/C++ | #include <MFstd.h>
void VF_setLinfitNeglect( float Thresh ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::setLinfitNeglect( const T& Thresh );
void matrix<T>::setLinfitNeglect( const T& Thresh ); |
Pascal/Delphi | uses MFstd;
procedure VF_setLinfitNeglect( Thresh:Single ); |
|
Description | As described in connection with VF_linfit, this function allows to define a significance threshold below which fit parameters ai are neglected. The default of this threshold is 4*FLT_EPSILON, 8*DLB_EPSILON, or 16*LDBL_EPSILON. The current threshold can be retrieved by VF_getLinfitNeglect. |
|
|
VF_setNonlinfitOptions
| VD_setNonlinfitOptions |
VE_setNonlinfitOptions |
|
Function | set options for the nonlinear fitting routines |
|
Syntax C/C++ | #include <MFstd.h>
void VF_setNonlinfitOptions( VF_NONLINFITOPTIONS *Options ); |
Pascal/Delphi | uses MFstd;
procedure VF_setNonlinfitOptions( Options: VF_NONLINFITOPTIONS ); |
|
Description | The nonlinear fitting routines like VF_nonlinfit offer the user a lot of different options, packed into a structure VF_NONLINFITOPTIONS (VD_NONLINFITOPTIONS and VE_NONLINFITOPTIONS for the higher accuracy data-types). These options may be set by the function V_setNonlinfitOptions. To retrieve current settings, use V_getNonlinfitOptions. The options set with this function are valid for all fitting-functions of the same accuracy level. Thus, e.g., VD_setNonlinfitOptions sets the options governing VD_nonlinfit, VD_multiNonlinfit, MD_nonlinfit, MD_multiNonlinfit and their siblings with data-weighting ("wW" versions). |
Example C/C++ | VD_NONLINFITOPTIONS Opt;
VD_getNonlinfitOptions( &Opt );
Opt.FigureOfMerit = 0; // choose least-square fitting
Opt.AbsTolChi = 1.e-6;
Opt.FracTolChi = 1.e-3; // make the fit fast, but not very accurate
Opt.LevelOfMethod = 3; // choose alternating Levenberg-Marquardt and Downhill-Simplex runs
VD_setNonlinfitOptions( &Opt ); |
Example Pascal/Delphi | Opt: VD_NONLINFITOPTIONS;
VD_getNonlinfitOptions(Opt );
Opt.FigureOfMerit := 0; (* choose least-square fitting *)
Opt.AbsTolChi := 1.e-6;
Opt.FracTolChi := 1.e-3; (* make the fit fast, but not very accurate *)
Opt.LevelOfMethod := 3; (* choose alternating Levenberg-Marquardt and Downhill-Simplex runs *)
VD_setNonlinfitOptions(Opt ); |
|
|
MF_setWriteFormat
| MD_setWriteFormat |
ME_setWriteFormat |
MCF_setWriteFormat |
MCD_setWriteFormat |
MCE_setWriteFormat |
|
Function | Definition of the format to be used by M?_write: C/C++ only! |
|
Syntax C/C++ | #include <MFstd.h>
void MF_setWriteFormat( char *FormatString ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::setWriteFormat( char *FormatString ); |
Pascal/Delphi | This function does not exist. |
|
Description | These functions are identical to the VF_setWriteFormat family.
The number format with which the M?_write functions print matrix elements into a stream can be adjusted by means of this function. When defining a write format, one should always be aware of the restrictions imposed by the read functions (not all formats you can write will be read correcly, see MF_read).
MF_setWriteFormat should not be used for the definition of whitespace between the columns. This is the task of MF_setWriteSeparate.
For details about the formats used for each of the various data types, please refer to the following table. The last column of this table gives the maximum length of the format string.
Version | Standard Format | Alternative Example | max. length |
MF_ | "% 11.8e" | "% 8.4f" | 16 |
MD_ | "% 19.16le" | "% 16.8lf" | 16 |
ME_ | "% 22.19Le" | "% 22.19LG" | 16 |
MCF_ | "% 11.8e, % 11.8e" | "{% 8.4f, % 8.4f}" | 32 |
MCD_ | "% 19.16le, % 19.16le" | "{% 19.16lE % 19.16lE}" | 32 |
MCE_ | "% 22.19Le, % 22.19Le" | "{% 22.19Lg % 22.19Lg}" | 32 |
|
|
Error handling | Format strings longer than the maximum length specified in the above table lead to a program abort with the error message "Invalid Parameter(s)".
The contents of the format string is not checked. So you have to be very careful to specify a format which is valid for the respective data type. |
|
|
MF_setWriteSeparate
| MD_setWriteSeparate |
ME_setWriteSeparate |
MCF_setWriteSeparate |
MCD_setWriteSeparate |
MCE_setWriteSeparate |
|
Function | define a character string used to separate columns in the M?_write functions |
|
Syntax C/C++ | #include <MFstd.h>
void MF_setWriteSeparate( char *SepString ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::setWriteSeparate( char *SepString ); |
Pascal/Delphi | uses MFstd;
procedure MF_setWriteSeparate( SepString:PChar ); |
|
Description | These functions are identical to the functions of the VF_setNWriteSeparate family. They are used to define the character string to be inserted between the columns of a table written by MF_write. MF_setWriteSeparate does not influence the end of each line which is always a line-feed character ('\n' for C/C++ and #13 for Pascal/Delphi).
SepString may contain up to twelve characters. The default setting is a single tab character ("\t" for C/C++ and #9 for Pascal/Delphi).
|
|
Error handling | In the case of SepString longer than twelve characters, the program is aborted with the error message "Invalid Parameter(s)".
The contents of SepString is not checked. |
|
|
MF_solve
| MD_solve |
ME_solve |
MCF_solve |
MCD_solve |
MCE_solve |
|
Function | solve a linear system |
|
Syntax C/C++ | #include <MFstd.h>
int MF_solve( fVector X, fMatrix A, fVector B, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::solve( const matrix<T>& MA, const vector<T>& B ); |
Pascal/Delphi | uses MFstd;
function MF_solve( X:fVector; MA:fMatrix; B:fVector; len:UInt ): IntBool; |
|
Description | This function solves the system MA * X = B of simultaneous linear equations, using LU decomposition. It works well in all cases where there is one unique solution. If successful, it returns FALSE (0).
If, on the other hand, the system is ill-determined, which happens in all cases where one or more of the equations are linear combinations of other equations of the same system, the resulting matrix becomes singular and the function fails with an error message, returning TRUE (1).
To avoid outright failure in an application where ill-determined matrices might occur, you should use
MF_LUDsetEdit to define a minimum "pivot" for the LU decomposition process. If you do so, MF_solve will always yield a "more or less" meaningful solution and returns always FALSE (0). Then, a call to MF_LUDresult will tell you if pivot-editing has actually been necessary.
Alternatively, you might switch to MF_safeSolve or MF_solveBySVD. |
|
Return value | FALSE (0), if the linear system could by solved; TRUE (1) in the case of a singular system without pivot-editing |
|
|
MF_solveBySVD
| MD_solveBySVD |
ME_solveBySVD |
|
Function | solve a possibly over- or underdetermined linear system by singular value decomposition |
|
Syntax C/C++ | #include <MFstd.h>
int MF_solveBySVD( fVector X, fMatrix A, fVector B, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::solveBySVD( const matrix<T>& MA, const vector<T>& B ); |
Pascal/Delphi | uses MFstd;
function MF_solveBySVD( X:fVector; MA:fMatrix; B:fVector; htA, lenA:UInt ): IntBool; |
|
Description | The system MA * X = B of simultaneous linear equations is solved for X, using Singular Value Decomposition. Here, underdetermined systems do not lead to an error. Rather, you get one particular solution out of the solution space. If you have more equations than unknowns, i.e., in the case of an overdetermined system, the solution vector contains a least-square "compromise" between the equations.
The function should always return FALSE (0). Only in the very rare case of SVD failure, TRUE (1) is returned. The length of the desired solution vector, sizX must be equal to the width of the input matrix, lenA, whereas the length of the right-hand-side vector, sizB must be equal to htA.
The threshold for singular-value editing should be set using MF_SVDsetEdit. |
|
Return value | usually FALSE (0); only in the very rare case of failure, TRUE (1) |
|
|
MF_spectrum
| MD_spectrum |
ME_spectrum |
|
Function | spatial frequency spectrum |
|
Syntax C/C++ | #include <MFstd.h>
void MF_spectrum( fMatrix Spec, unsigned htSpec, unsigned lenSpec, fMatrix X, unsigned htX, unsigned lenX, fMatrix Win ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::sprectrum( const matrix<T>& MX, const matrix<T>& MWin ); |
Pascal/Delphi | uses MFstd;
procedure MF_spectrum( MSpec:fMatrix; htSpec, lenSpec:UInt; MX:fMatrix; htX, lenX:UInt; MWin:fMatrix ); |
|
Description | The data set MX is analyzed for the mean square amplitude of its spatial frequency spectrum. The result is stored in MSpc.
Internally, the spectrum is calculated by dividing the input data into overlapping segments, similarly to the one-dimensional case described for VF_spectrum.
MWin is a window that is applied to the data segments. Three functions are available that give suitable
Windows: MF_Welch, MF_Parzen, and MF_Hanning. A square window is available by setting all matrix elements equal to 1.0 (MF_equC( MWin, htWin, lenWin, 1.0 ); ), but this is not recommended.
htSpec and lenSpec must be integer powers of 2.
MSpec has [htSpec+1][lenSpec+1] elements (!), and htX >= n*htSpec, lenX >= n*lenSpec, htWin = 2*htSpec, lenWin = 2*lenSpec.
About special versions with the prefixes MFs_ and MFl_, consult chapter 4.8 of HANDBOOk.HTM. |
|
Error handling | If either htSpec or lenSpec is not a power of 2, VF_FFT (on which MF_spectrum relies) complains "Size must be an integer power of 2" and the program is aborted. If MSpc overwrites MX or MWin, an error message "Vectors/matrices must not be identical" is generated and the program aborted. |
|
|
MFsym_sqrt
| MDsym_sqrt |
MEsym_sqrt |
|
Function | Square root of a symmetric, positive definite matrix |
|
Syntax C/C++ | #include <MFstd.h>
int MFsym_sqrt( fMatrix B, fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::sqrt( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
function MFsym_sqrt( MB, MA:fMatrix; len:UInt ):IntBool; |
|
Description | The square-root of a symmetric, positive definite matrix is calculated, so that MB * MB = MA is satisfied. Please note that non-symmetric matrices or matrices which are not positive definite may or may not have existing square-roots, too. The present algorithm, however, is restricted to the most simple case where a square-root always exists. It uses eigenvalues and eigenvectors and fails whenever a negative eigenvalue is encountered, indicating an input matrix which is not positive definite. In the latter case, an error message is displayed and the result is calculated with zero substituted for the negative eigenvalue. This result may still be useful, namely if the negative eigenvalue is very small.
A return value of FALSE or 0 indicates success, whereas a non-zero return value indicates that the input matrix did not meet the condition of being symmetric and positive definite. |
|
Return value | FALSE (0), if the matrix square-root could be calculated; otherwise TRUE (1) |
|
|
MF_store
| MD_store |
ME_store |
MCF_store |
MCD_store |
MCE_store |
|
Function | store a matrix in binary format into a stream |
|
Syntax C/C++ | #include <MFstd.h>
void MF_store( FILE *stream, fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::store( FILE *stream ); |
Pascal/Delphi | uses MFstd;
procedure MF_store( var Stream:FILE; MA:fMatrix; ht, len:UInt ); |
|
Description | The matrix MA of ht*len elements is written to stream in binary format. The stream must be already open for binary write operations. |
|
|
MFs_subM |
MDs_subM |
MEs_subM |
MCF_subM |
MCD_subM |
MCE_subM |
|
Function | element-wise subtraction of two matrices |
|
Syntax C/C++ | #include <MFstd.h>
void MF_subM( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len );
void MFs_subM( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::subM( const matrix<T>& MA, const matrix<T>& MB);
void matrix<T>::s_subM( const matrix<T>& MA, const matrix<T>& MB, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_subM( MC, MA, MB:fMatrix; ht, len:UInt );
procedure MFs_subM( MC, MA, MB:fMatrix; ht, len:UInt; C:Single ); |
|
Description | normal version: MCij = MAij - MBij
scaled version: MCij = C * (MAij - MBij) |
|
|
MF_subMT
| MD_subMT |
ME_subMT |
MFs_subMT |
MDs_subMT |
MEs_subMT |
MCF_subMT |
MCD_subMT |
MCE_subMT |
|
Function | subtract the transpose of one matrix from another matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_subMT( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len );
void MFs_subMT( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::subMT( const matrix<T>& MA, const matrix<T>& MB);
void matrix<T>::s_subMT( const matrix<T>& MA, const matrix<T>& MB, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_subMT( MC, MA, MB:fMatrix; ht, len:UInt );
procedure MFs_subMT( MC, MA, MB:fMatrix; ht, len:UInt; C:Single ); |
|
Description | normal version: MCi,j = MAi,j - MBTj,i
scaled version: MCi,j = C * (MAi,j - MBTj,i) |
|
|
MF_subrMT
| MD_subrMT |
ME_subrMT |
MFs_subrMT |
MDs_subrMT |
MEs_subrMT |
MCF_subrMT |
MCD_subrMT |
MCE_subrMT |
|
Function | reverse subtraction: subtract one matrix from the transpose of another |
|
Syntax C/C++ | #include <MFstd.h>
void MF_subrMT( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len );
void MFs_subrMT( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len, float C ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::subrMT( const matrix<T>& MA, const matrix<T>& MB);
void matrix<T>::s_subrMT( const matrix<T>& MA, const matrix<T>& MB, const T& C); |
Pascal/Delphi | uses MFstd;
procedure MF_subrMT( MC, MA, MB:fMatrix; ht, len:UInt );
procedure MFs_subrMT( MC, MA, MB:fMatrix; ht, len:UInt; C:Single ); |
|
Description | normal version: MCi,j = MBTj,i - MAi,j
scaled version: MCi,j = C * (MBTj,i - MAi,j) |
|
|
MF_submatrix
| MD_submatrix |
ME_submatrix |
MCF_submatrix |
MCD_submatrix |
MCE_submatrix |
|
Function | extract a submatrix from a (larger) matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_submatrix( fMatrix Sub, unsigned subHt, unsigned subLen, fMatrix Srce, unsigned srceHt, unsigned srceLen, unsigned firstRowInCol, unsigned sampInCol, unsigned firstColInRow, unsigned sampInRow ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::submatrix( const matrix<T>& MSrce, const unsigned firstRowInCol, const unsigned sampInCol, const unsigned firstColInRow, const unsigned sampInRow ); |
Pascal/Delphi | uses MFstd;
procedure MF_submatrix( MSub:fMatrix; subHt, subLen:UInt; MSrce:fMatrix; srceHt, srceLen:UInt; firstRowInCol, sampInCol, firstColInRow, sampInRow:UInt ); |
|
Description | MSubi, j = MSrcei*sampInCol+firstRowInCol, j*sampInRow+firstColInRow |
|
|
MF_submatrix_equM
| MD_submatrix_equM |
ME_submatrix_equM |
MCF_submatrix_equM |
MCD_submatrix_equM |
MCE_submatrix_equM |
|
Function | distribute the elements of a matrix to a submatrix of another (larger) matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_submatrix_equM( fMatrix Dest, unsigned destHt, unsigned destLen, unsigned firstRowInCol, unsigned sampInCol, unsigned firstColInRow, unsigned sampInRow, fMatrix Srce, unsigned srceHt, unsigned srceLen ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::submatrix_equM( const unsigned firstRowInCol, const unsigned sampInCol, const unsigned firstColInRow, const unsigned sampInRow, const matrix<T>& MSrce ); |
Pascal/Delphi | uses MFstd;
procedure MF_submatrix_equM( MDest:fMatrix; destHt, destLen, firstRowInCol, sampInCol, firstColInRow, sampInRow:UInt;
MSrce:fMatrix; srceHt, srceLen:UInt ); |
|
Description | MDesti*sampInCol+firstRowInCol, j*sampInRow+firstColInRow = MSrcei, j
This function does the inverse of MF_submatrix |
|
|
MF_SVdecompose
| MD_SVdecompose |
ME_SVdecompose |
|
Function | Singular Value Decomposition |
|
Syntax C/C++ | #include <MFstd.h>
int MF_SVdecompose( fMatrix U, fMatrix V, fVector W, fMatrix A, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
int matrix<T>::SVdecompose( matrix<T> MV, vector<T> W, const matrix<T>& MA );
int matrix<T>::SVdecompose( matrix<T>* MV, vector<T>* W, const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
function MF_SVdecompose( MU, MV:fMatrix; W:fVector; MA:fMatrix; htA, lenA:UInt ): IntBool; |
|
Description | The matrix MA of dimensions [ht, len] is decomposed into a product
MA = MU * MW * MVT,
where MU has the dimensions [max(ht,len), len]. MW is a diagonal matrix with all elements positive or zero. Actually, only the diagonal of this matrix is stored in the vector W of size [len], MV, finally, is a square matrix [len, len]. Both MU and MV are orthogonal:
MUT * MU = MVT * MV = (1).
Due to these orthogonality relations, the solution of a linear system MA * X = B is straightforward, once MA has been singular-value decomposed:
X = MV * W-1 * MUT
(This equation must be evaluated from right to left.) As MU and MV are orthogonal, only W must explicitly be inverted. This, however, is again easy, as W is diagonal, and the inverse of a diagonal matrix consists of the inverse of the diagonal elements. This is the important point which makes SVD so useful, because it provides both a diagnose and a cure for singularities. If any element of W is very small compared to the largest element, this corresponds to a singularity (at least in the numerical sense, where dividing by extremely small numbers is almost as bad as dividing by zero). A singularity means that the underlying linear system is under-determined. This, in turn, means that one can arbitrarily choose one particular solution. Specifically, one may choose W-1ii = 0 for very small Wii, which is one of the rare cases where it makes sense to set the result of a division by (near-)zero to zero instead of infinity. This reduction of the dimension by "Singular Value editing" is the crucial point in all functions relying on SVD, like MF_SVsolve, MF_safeSolve), VF_linfit and others. The editing threshold is set by MF_SVDsetEdit.
This function may not be called while the FPU is set to reduced accuracy, or else it might fail to achieve convergence. See V_setFPAccuracy.
If you compare results of MF_SVdecompose with SVD-routines of other vendors, please note the following points:
- MF_SVdecompose itself does not perform a dimension reduction (replacement of small singular values by 0), but leaves this step to following functions or to manual inspection by the user.
- Singular values can be permutated, if the same permutation is also applied to the corresponding columns of both MU and MV. Sometimes, this property of SVD is exploited to bring the singular values into a certain (for example, into descending) order. As the price for this increased beauty is an increased work-load, MF_SVdecompose keeps the singular values in arbitrary order.
- The sign of a singular value may be exchanged if the corresponding column of MV is also multiplied by -1. MF_SVdecompose uses this property to make all non-vanishing singular values positive.
|
|
|
MF_SVDgetEdit
| MD_SVDgetEdit |
ME_SVDgetEdit |
|
Function | retrieve current editing threshold for Singular Value backsubstitution |
|
Syntax C/C++ | #include <MFstd.h>
float MF_SVDgetEdit( void ); |
C++ MatObj | #include <OptiVec.h>
T matrix<T>::SVDgetEdit( ); |
Pascal/Delphi | uses MFstd;
function MF_SVDgetEdit: Single; |
|
Description | This function returns the current Singular Value editing threshold. The SV editing threshold may be modified by MF_SVDsetEdit. |
|
Return value | current SV editing threshold |
|
|
MF_SVDsetEdit
| MD_SVDsetEdit |
ME_SVDsetEdit |
|
Function | set the Singular Value editing threshold |
|
Syntax C/C++ | #include <MFstd.h>
void MF_SVDsetEdit( float Thresh ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::SVDsetEdit( const T& Thresh ); |
Pascal/Delphi | uses MFstd;
procedure MF_SVDsetEdit( Thresh:Single ); |
|
Description | As described in connection with MF_SVdecompose and MF_SVsolve, the crucial point in using functions which rely on Singular Value Decomposition is the Singular Value editing step. By default, the SV editing threshold is 4*FLT_EPSILON, 8*DBL_EPSILON, or 16*LDBL_EPSILON. You may change these values by calling MF_SVDsetEdit. To retrieve the current SV editing threshold, call MF_SVDgetEdit. |
|
|
MF_SVsolve
| MD_SVsolve |
ME_SVsolve |
|
Function | solve a system of linear equations, given its Singular Value decomposed form |
|
Syntax C/C++ | #include <MFstd.h>
void MF_SVsolve( fVector X, fMatrix U, fMatrix V, fVector W, fVector B, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::SVsolve( const matrix<T>& MU, const matrix<T>& MV, const vector<T>& W, const vector<T>& B ); |
Pascal/Delphi | uses MFstd;
procedure MF_SVsolve( X:fVector; MU, MV:fMatrix; W, B:fVector; htA, lenA:UInt ); |
|
Description | MF_SVsolve solves an SV-decomposed set of linear equations; sometimes this process is also called Singular Value Backsubstitution. In this function, at first W is edited such that elements smaller than a threshold are set to zero. Then, in the backsubstitution process, which involves divisions by the elements of W, any divisions by Wi = 0 are replaced by setting the result to 0. You can choose the editing threshold by calling MF_SVDsetEdit. If you prefer to inspect and edit W yourself before calling MF_SVsolve, you can call MF_SVDsetEdit with the argument 0.0, thereby switching off the automatic SV editing.
The parameters htA and lenA refer to the original matrix MA as fed into MF_SVdecompose. The actual dimensions of the vectors and matrices entered into MF_SVsolve are:
sizeB = htA;
sizeX = htU = max( lenA, htA );
sizeW = lenU = htV = lenV = lenA; |
|
|
MF_TmulM
| MD_TmulM |
ME_TmulM |
MCF_TmulM |
MCD_TmulM |
MCE_TmulM |
|
Function | multiply the transpose of one matrix by another matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_TmulM( fMatrix C, fMatrix A, fMatrix B, unsigned htA, unsigned lenA, unsigned lenB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::TmulM( const matrix<T>& MA, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MF_TmulM( MC, MA, MB:fMatrix; htA, lenA, lenB:UInt ); |
|
Description | MC = MAT * MB
htA, lenA, and lenB must be specified; the other dimensions are implicitly given as: htB = htA, lenC = lenB, htC = lenA. htA and lenA refer to the original, un-transposed input matrix. |
|
|
MF_TmulMdia
| MD_TmulMdia |
ME_TmulMdia |
MCF_TmulMdia |
MCD_TmulMdia |
MCE_TmulMdia |
|
Function | multiply the transpose of a general matrix by a diagonal matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_TmulMdia( fMatrix C, fMatrix A, fVector MBDia, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::mulMdia( const matrix<T>& MA, const vector<T>& MBDia, ); |
Pascal/Delphi | uses MFstd;
procedure MF_TmulMdia( MC, MA:fMatrix; MBDia:fVector; htA, lenA:UInt ); |
|
Description | MC = MAT * MBDia
htA and lenA must be specified. They refer to the original, un-transposed input matrix. Implicitly, sizB = htA. |
|
|
MF_TmulMT
| MD_TmulMT |
ME_TmulMT |
MCF_TmulMT |
MCD_TmulMT |
MCE_TmulMT |
|
Function | multiply the transpose of one matrix by the transpose of another |
|
Syntax C/C++ | #include <MFstd.h>
void MF_TmulMT( fMatrix C, fMatrix A, fMatrix B, unsigned htA, unsigned lenA, unsigned htB ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::TmulMT( const matrix<T>& MA, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MF_TmulMT( MC, MA, MB:fMatrix; htA, lenA, htB:UInt ); |
|
Description | MC = MAT * MBT
htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = htA, lenC = htB, htC = lenA. All dimensions refer to the original, un-transposed input matrices. |
|
|
MF_TmulV
| MD_TmulV |
ME_TmulV |
MCF_TmulV |
MCD_TmulV |
MCE_TmulV |
|
Function | multiply the transpose of a matrix by a column vector |
|
Syntax C/C++ | #include <MFstd.h>
void MF_TmulV( fVector Y, fMatrix A, fVector X, unsigned htA, unsigned lenA ); |
C++ MatObj | #include <OptiVec.h>
void vector<T>::TmulV( const matrix<T>& MA, const vector<T>& X ); |
Pascal/Delphi | uses MFstd;
procedure MF_TmulV( Y:fVector; MA:fMatrix; X:fVector; htA, lenA:UInt ); |
|
Description | Y = MAT * X
The dimensions htA and lenA refer to the original (rather than the intermediate transposed) matrix MA; the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = htA, sizY = lenA. |
|
|
MF_transpose
| MD_transpose |
ME_transpose |
MCF_transpose |
MCD_transpose |
MCE_transpose |
|
Function | transpose of a matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_transpose( fMatrix Tr, fMatrix A, unsigned htTr, unsigned lenTr ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::transpose( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_transpose( MTr, MA:fMatrix; htTr, lenTr:UInt ); |
|
Description | MTri,j = MAj,i
The dimensions fed into this function, htTr and lenTr, refer to the transposed matrix rather than to the input matrix. |
|
|
MF_Trd_equM
| MD_Trd_equM |
ME_Trd_equM |
MCF_Trd_equM |
MCD_Trd_equM |
MCE_Trd_equM |
|
Function | initialize the tridiagonal part of a matrix with the three vectors contained in a compacted tradiagonal matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Trd_equM( fMatrix A, fMatrix Trd, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Trd_equM( const matrix<T>& MTrd ); |
Pascal/Delphi | uses MFstd;
procedure MF_Trd_equM( MA, MTrd:fMatrix; len:UInt ); |
|
Description | Row 0 of MTrd is copied into the first diagonal above the main diagonal of the square matrix MA. Row 1 of MTrd goes into the main diagonal of MA, and Row 2 of MTrd into the first diagonal below the main diagonal of MA. See chapter 1.2 for details about the storing of tridiagonal matrices. |
|
|
MF_Trd_extract
| MD_Trd_extract |
ME_Trd_extract |
MCF_Trd_extract |
MCD_Trd_extract |
MCE_Trd_extract |
|
Function | extract the tridiagonal part from a general matrix and store it into a compacted tridiagonal matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Trd_extract( fMatrix Trd, fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Trd_estract( const matrix<T>& MA ); |
Pascal/Delphi | uses MFstd;
procedure MF_Trd_extract( MTrd, MA:fMatrix; len:UInt ); |
|
Description | The first diagonal above the main diagonal of the square matrix MA is copied into Row 0 of MTrd. The main diagonal of MA goes into Row1 of MTrd, and the first diagonal below the main diagonal of MA is copied into Row 2 of MTrd. See chapter 1.2 for details about the storing of tridiagonal matrices. |
|
|
MF_UequL
| MD_UequL |
ME_UequL |
MCF_UequL |
MCD_UequL |
MCE_UequL |
|
Function | copy lower-diagonal elements into upper-diagonal by index-reflection, so as to get a symmetric matrix |
|
Syntax C/C++ | #include <MFstd.h>
void MF_UequL( fMatrix A, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::UequL( ); |
Pascal/Delphi | uses MFstd;
procedure MF_UequL( MA:fMatrix; len:UInt ); |
|
Description | MAi,j = MAj,i, i < j |
|
|
MF_Welch
| MD_Welch |
ME_Welch |
|
Function | two-dimensional Welch window for use in spatial frequency analysis |
|
Syntax C/C++ | #include <MFstd.h>
void MF_Welch( fMatrix A, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::Welch( ); |
Pascal/Delphi | uses MFstd;
procedure MF_Welch( MA:fMatrix; ht, len:UInt ); |
|
Description | MAi,j = (1 - ( (i - 0.5*(ht - 1)) / (0.5*(ht + 1)) )2) * (1 - ( (j - 0.5*(len - 1)) / (0.5*(len + 1)) )2) |
|
|
MF_write
| MD_write |
ME_write |
MCF_write |
MCD_write |
MCE_write |
|
Function | write a matrix in ASCII format into a stream |
|
Syntax C/C++ | #include <MFstd.h>
void MF_write( FILE *stream, fMatrix X, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::write( FILE *stream ); |
Pascal/Delphi | uses MFstd;
{Delphi version:}
procedure MF_write( var Stream:TextFile; MA:fMatrix; ht, len:UInt );
{Turbo Pascal version:}
procedure MF_write( var Stream:Text; MA:fMatrix; ht, len:UInt ); |
|
Description | The matrix MA with len columns and ht rows is written to stream in ASCII format. stream must already be open for write operations in text format.
The number format and the separation between columns may be specified using MF_setWriteFormat (C/C++ only) and MF_setWriteSeparate, respectively. See these functions for details.
Storing data in ASCII format is useful if the data have to be readable by human eyes, or if they are to be exported into other programs which are not able to read machine-format numbers. If avoidable, these functions should not be used for the storage of intermediate results that later have again to be read in. Instead, the function pairs of the MF_store / MF_recall family are recommended for the following reasons: conversion into ASCII format is slow, may lead to round-off errors, and requires much more disk memory than storage in machine format.
|
|
|
|
MF_xcorr
| MD_xcorr |
ME_xcorr |
|
Function | spatial cross-correlation function |
|
Syntax C/C++ | #include <MFstd.h>
void MF_xcorr( fMatrix C, fMatrix A, fMatrix B, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::xcorr( const matrix<T>& MA, const matrix<T>& MB ); |
Pascal/Delphi | uses MFstd;
procedure MF_xcorr( MC, MA, MB:fMatrix; ht, len:UInt ); |
|
Description | The spatial cross-correlation function (SCCF) of MA and MB is calculated and stored in MC in wrap-around order in both dimensions: The row elements MCi,0 to MCi,len/2-1 contain the SCCF for zero and positive x lags. Beginning with the most negative lag in MCi,len/2+1, the elements up to MCi,len-1 contain the SCCF for negative lags. Since this function assumes MA and MB to be periodic, the SCCF for the most positive lag is identical to the SCCF for the most negative lag. This element is stored as MCi,len/2.
Similarly, the column elements MC0,j to MClen/2-1,j contain the SCCF for zero and positive y lags. Beginning with the most negative lag in MClen/2+1,j, the elements up to MClen-1,j contain the SCCF for negative lags.
To get the SCCF into normal order, you may call
MF_Rows_rotate( MC, ht, len, len/2 );
MF_Cols_rotate( MC, ht, len, ht/2 );
After that, the zero point is at the position MCht/2,len/2.
In case MA or MB are non-periodic, you should avoid end effects by the methods described in connection with MF_convolve.
All three matrices involved have the same dimensions. Both ht and len must be integer powers of 2.
About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM. |
|
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_xcorr is based) complains "Size must be an integer power of 2" and the program is aborted. |
|
|
MF_xyzAutoDensityMap
| MD_xyzAutoDensityMap |
ME_xyzAutoDensityMap |
|
Function | draw an X-Y coordinate system and plot a color-density map for z = f( x, y ) into it |
|
Syntax C/C++ | #include <Mgraph.h>
void MF_xyzAutoDensityMap( fVector X, fVector Y, fMatrix Z, unsigned ht, unsigned len, COLORREF mincolor, COLORREF maxcolor ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::xyzAutoDensityMap( const vector<T>& X, const vector<T>& Y, COLORREF mincolor, COLORREF maxcolor ); |
Pascal/Delphi | uses Mgraph;
procedure MF_xyzAutoDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt; mincolor, maxcolor: COLORREF ); |
|
Description | A Cartesian coordinate system is drawn with automatic scaling of the axes and the matrix MZ is plotted as a color-density map against the vectors X and Y. Prior to calling MF_xyzAutoDensityMap, the plotting routines have to be initialized by V_initGraph (for DOS programs) or V_initPlot (DOS or Windows programs).
The font of the axis tick labels is the actual text font. In DOS programs (Borland C++ or Pascal), it may be changed by calling settextstyle before calling MF_xyzAutoDensityMap. In Windows programs (both 16-bit and 32-bit), the font of the current device context is used.
All MZ values will be translated into colors by linear interpolation between the parameters mincolor and maxcolor.
DOS: The data type COLORREF is unsigned. See the Borland C++ or TurboPascal function setcolor for a description of the colors available in the various graphics modes.
Windows: The data type COLORREF is unsigned long. The colors BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW, and WHITE are defined in <Vgraph.h> (or the unit Vgraph) by analogy with the COLORS defined for DOS in <graphics.h> (or the unit Graph) for the BGI routines. Thereby, portability between DOS and Windows programs is improved. For programs designed to run exclusively under Windows, it is nevertheless recommended to use fine-tuned colors defined by the RGB macro, instead of the predefined colors.
If you wish to define the boudaries of the coordinate system differently, instead of relying on the automatic range detection and scaling, you may call first M_setDensityMapBounds or (for preserved automatic scaling, but with arbitrary x and y ranges) MF_findDensityMapBounds. Subsequently, call MF_xyzDataDensityMap instead of MF_xyzAutoDensityMap. |
|
|
MF_xyzDataDensityMap
| MD_xyzDataDensityMap |
ME_xyzDataDensityMap |
|
Function | plot a color density map z = f( x, y ) into an existing coordinate system with a previously defined color scale |
|
Syntax C/C++ | #include <Mgraph.h>
void MF_xyzDataDensityMap( fVector X, fVector Y, fMatrix Z, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::xyzDataDensityMap( const vector<T>& X, const vector<T>& Y ); |
Pascal/Delphi | uses Mgraph;
procedure MF_xyzDataDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt ); |
|
|
|
MF_zAutoDensityMap
| MD_zAutoDensityMap |
ME_zAutoDensityMap |
|
Function | plot a color density map of a matrix against the indices over its dimensions |
|
Syntax C/C++ | #include <Mgraph.h>
void MF_zAutoDensityMap( fMatrix Z, unsigned ht, unsigned len, COLORREF mincolor, COLORREF maxcolor ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::zAutoDensityMap( COLORREF mincolor, COLORREF maxcolor ); |
Pascal/Delphi | uses Mgraph;
procedure MF_xyzDataDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt ); |
|
Description | This function is similar to MF_xyzAutoDensityMap, but here MZ is plotted against the indices of its dimensions instead of explicit X and Y values. |
|
|
MF_zDataDensityMap
| MD_zDataDensityMap |
ME_zDataDensityMap |
|
Function | plot a color-density map of a matrix into an existing coordinate system whose axes comprise the range of the indices of the matrix dimensions |
|
Syntax C/C++ | #include <Mgraph.h>
void MF_zDataDensityMap( fMatrix Z, unsigned ht, unsigned len ); |
C++ MatObj | #include <OptiVec.h>
void matrix<T>::zDataDensityMap( ); |
Pascal/Delphi | uses Mgraph;
procedure MF_zDataDensityMap( MZ:fMatrix; ht, len: UInt ); |
|
Description | This function is similar to MF_xyzDataDensityMap, but here MZ is plotted against the indices of its dimensions instead of explicit X and Y values. |
|
|
MF_2DArrayToMatrix
| MD_2DArrayToMatrix |
ME_2DArrayToMatrix |
MCF_2DArrayToMatrix |
MCD_2DArrayToMatrix |
MCE_2DArrayToMatrix |
|
Function | convert 2D-array of Delphi 4 or higher into OptiVec matrix |
|
Syntax C/C++ | N.A. |
Pascal/Delphi | uses MFstd, VecLib;
type fArray = array of Single;
type f2DArray = array of fArray;
procedure MF_2DArrayToMatrix( MF:fMatrix; DelphiArr:f2DArray; ht,len:UInt); |
|
Description | This function is necessary only for Delphi 4 or higher. (Previous versions of Borland Pascal/Delphi did not support dynamically allocated matrices.) It converts two-dimensional Delphi arrays into OptiVec matrices. Note that, unlike static Pascal/Delphi matrices, the dynamic matrices of Delphi 4+ cannot directly be passed to OptiVec functions, but have to be converted first. |
|
|
Back to Table of Contents
E N D
Copyright for OptiVec software and documentation
© 1996-2004 OptiCode - Dr. Martin Sander Software Dev.
All rights reserved!