OptiVec

Version 3


for C/C++ and for Pascal/Delphi

OptiCode
Dr. Martin Sander Software Development
Steinachstr. 9A
D-69198 Schriesheim
Germany
http://www.optivec.com
e-mail: support@optivec.com or
sales@optivec.com

Part II: MatrixLib

 
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:
fMatrixmatrix of floats
dMatrixmatrix of doubles
eMatrixmatrix of extended (long double)
cfMatrixmatrix of fComplex (complex<float>)
cdMatrixmatrix of dComplex (complex<double>)
ceMatrixmatrix 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:

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:

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_matrixallocate memory for a matrix
MF_matrix0allocate memory and set all elements 0
M_freefree one matrix (data-type independent)
M_nfreefree n matrices (data-type independent; only C/C++)
V_freeAllfree 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++:
MF_PelementPointer to a specific matrix element
MF_elementvalue of a specific matrix element

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_equ0set all elements to 0
MF_equ1identity matrix: set all diagonal elements to 1.0, all others to 0
MF_equm1negative identity matrix: set all diagonal elements to -1.0, all others to 0
MF_randomfill with random numbers
MF_outerprodmatrix formed by the "outer product" of two vectors
MF_Row_equ0set all elements of one specific row to 0
MF_Col_equ0set all elements of one specific column to 0
MF_Dia_equ0set all diagonal elements to 0
MF_Row_equCset all elements of one specific row to the constant C
MF_Col_equCset all elements of one specific column to the constant C
MF_Dia_equCset all diagonal elements to the constant C
MF_Row_equVcopy a vector into one specific row
MF_Col_equVcopy a vector into one specific column
MF_Dia_equVcopy a vector into the diagonal
MF_Trd_equMcopy a compacted tridiagonal matrix into a general matrix
MF_equMmake one matrix the copy of another
MF_negmake one matrix the negative of another
MCF_conjmake one matrix the complex conjugate of another
MCF_hermconjmake one matrix the Hermitian conjugate of another: MB = MAT*
MF_UequLcopy lower-diagonal elements into upper-diagonal by index-reflection, so as to get a symmetric matrix
MF_LequUcopy upper-diagonal elements into lower-diagonal
 
Two-dimensional windows for spectral analysis are provided by: 
MF_HanningHanning window
MF_ParzenParzen window
MF_WelchWelch window

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_FtoDfMatrix to dMatrix
M_EtoDeMatrix to dMatrix (with overflow protection)
M_CDtoCFcdMatrix to cfMatrix (with overflow protection)
M_DtoEdMatrix to eMatrix

Back to Table of Contents


5. Transposing, Augmenting, Deleting, Extracting, and Filling Parts from a Matrix

MF_transposetranspose a matrix: MB = MAT
MCF_hermconjHermitian conjugate: MB = MAT*
MF_equMblockextract a block, i.e. a submatrix for which the sampling interval both along rows and along columns is 1
MF_equMblockTextract the transpose of a block
MF_submatrixextract a submatrix with sampling intervals along rows and/or columns possibly different from 1
MF_block_equMcopy a matrix back into a block of another (normally larger) matrix
MF_block_equMTcopy the transpose of a matrix into a block of another (normally larger) matrix
MF_submatrix_equMcopy a submatrix back into another (normally larger) matrix
MF_Row_extractextract a single row and copy it into a vector
MF_Col_extractextract a single column and copy it into a vector
MF_Dia_extractextract the diagonal and copy it into a vector
MF_Trd_extractextract a tridiagonal matrix from a general matrix
MF_Row_insertaugment a matrix by insertion of one row
MF_Col_insertaugment a matrix by insertion of one column
MF_Row_deletedelete one row of a matrix
MF_Col_deletedelete one column of 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_addCadd a constant to all elements of a specific row
MF_Col_addCadd a constant to all elements of a specific column
MF_Dia_addCadd a constant to all diagonal elements
MF_Row_addVadd corresponding vector elements to all elements of a specific row
MF_Col_addVadd corresponding vector elements to all elements of a specific column
MF_Dia_addVadd corresponding vector elements to the diagonal elements
 
A few examples should suffice for the other functions of this family: 
MF_Row_subCsubtract a constant from all elements of a specific row
MF_Col_subrCreverse substraction: difference between column elements and a constant
MF_Dia_mulVmultiply the diagonal elements with corresponding vector elements
MF_Row_divVdivide all elements of a specific row by corresponding vector elements
MF_Col_divrCreverse 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

MF_Rows_maxstore the maxima of all rows in a column vector
MF_Cols_maxstore the maxima of all colums in a row vector
MF_Dia_maxreturn the maximum of the diagonal as a scalar
MF_Rows_absmaxstore the absolute maxima of all rows in a column vector
MF_Cols_absmaxstore the absolute maxima of all colums in a row vector
MF_Dia_absmaxreturn the absolute maximum of the diagonal as a scalar
MF_Rows_sumsum, taken along rows and stored in a column vector
MF_Cols_sumsum, taken along colums and stored in a row vector
MF_Dia_sumsum of the diagonal elements
MF_Rows_prodproduct, taken along rows and stored in a column vector
MF_Cols_prodproduct, taken along colums and stored in a row vector
MF_Dia_prodproduct of the diagonal elements
MF_Rows_runsumrunning sum along rows
MF_Cols_runsumrunning sum along columns
MF_Rows_runprodrunning product along rows
MF_Cols_runprodrunning product along columns
MF_Rows_rotaterotate all rows by a specified number of positions
MF_Cols_rotaterotate all columns by a specified number of positions
MF_Rows_reflectset the upper halves of all rows equal to their reversed lower halves
MF_Cols_reflectset the upper halves of all columns equal to their reversed lower halves

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_absmaxstore the maxima of the absolute values of all rows in a (real-valued) column vector
MCF_Cols_absmaxstore the maxima of the absolute values of all colums in a (real-valued) row vector
MCF_Dia_absmaxreturn the maximum of the absolute values of the diagonal elements as a (real) scalar
MCF_Rows_absmaxReImfind 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_absmaxReImfind 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_absmaxReImfind 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_cabsmaxfind the complex numbers of largest magnitude along rows and store these row maxima in a (complex) column vector
MCF_Cols_cabsmaxfind the complex numbers of largest magnitude along columns and store these column maxima in a (complex) row vector
MCF_Dia_cabsmaxfind the complex number of largest magnitude along the diagonal of a square matrix and return it as a (complex) scalar
MCF_Rows_maxReImfind 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_maxReImfind 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_maxReImfind 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_sabsmaxfind the complex numbers of largest sum |Re|+|Im| along rows and store these row maxima in a (complex) column vector
MCF_Cols_sabsmaxfind the complex numbers of largest sum |Re|+|Im| along columns and store these column maxima in a (complex) row vector
MCF_Dia_sabsmaxfind 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

MF_Rows_exchangeexchange two rows
MF_Cols_exchangeexchange two columns
MF_Rows_addadd one row to another (destination += source)
MF_Cols_addadd one column to another
MF_Rows_subsubtract one row from another (destination -= source)
MF_Cols_subsubtract one column from another
MF_Rows_Caddadd scaled row to another (destination += C * source)
MF_Cols_Caddadd scaled column to another
MF_Rows_lincomblinear combination of two rows
MF_Cols_lincomblinear combination of two columns

Back to Table of Contents


9. Whole-Matrix Arithmetics: Addition, Multiplication

a) Element-wise operations
MF_addMadd two matrices
MF_addMTadd one matrix and the transpose of another matrix
MC = MA + MBT
MF_subMsubtract one matrix from another
MF_subMTsubtract a transposed matrix
MC = MA - MBT
MF_subrMTsubtract a matrix from another, transposed, matrix
MC = MBT - MA
MF_mulCmultiply all matrix elements by a constant
MCF_mulReCmultiply all elements of a complex matrix by a real number
MF_divCdivide all matrix elements by a constant
MCF_divReCdivide all elements of a complex matrix by a real number
MFs_addMscaled addition of two matrices:
MC = c * (MA + MB)
MFs_addMTscaled addition of one matrix and the transpose of another:
MC = c * (MA + MBT)
MFs_subMscaled subtraction of two matrices:
MC = c * (MA - MB)
MFs_subMTscaled subtraction of one matrix and the transpose of another:
MC = c * (MA - MBT)
MFs_subrMTscaled reverse subtraction of one matrix and the transpose of another:
MC = c * (MBT - MA)
MF_lincomblinear combination:
MC = ca * MA + cb * MB

b) Matrix multiplication:
MF_mulVmultiply a matrix by a column vector:
Y = MA * X
MF_TmulVmultiply the transpose of a matrix by a column vector:
Y = MAT * X
VF_mulMmultiply a row vector by a matrix:
Y = X * MA
VF_mulMTmultiply a row vector by the transpose of a matrix:
Y = X * MAT
MF_mulMmultiply two matrices:
MC = MA * MB
MF_mulMTmultiply one matrix by the transpose of another matrix:
MC = MA * MBT
MF_TmulMmultiply the transpose of a matrix by another matrix:
MC = MAT * MB
MF_TmulMTmultiply the transpose of one matrix by the transpose of another matrix:
MC = MAT * MBT
MCF_mulMJmultiply one matrix by the hermitian conjugate of another matrix:
MC = MA * MBT *
MCF_HmulMmultiply 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_mulMdiamultiply a general matrix by a diagonal matrix:
MC = MA * MBDia
MF_TmulMdiamultiply the transpose of a matrix by a diagonal matrix:
MC = MAT * MBDia
MFdia_mulMmultiply a diagonal matrix by a general matrix:
MC = MADia * MB
MFdia_mulMTmultiply 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_invinvert a matrix
MF_detdeterminant of a matrix
MF_solveBySVDsolve simultaneous linear equations, using Singular Value Decomposition
MF_safeSolvetries first solution by LUD; if that fails, SVD is done
 
Now some functions for explicit LU decomposition and for treatment of LU decomposed matrices:
MF_LUdecompose decompose into LU form
MF_LUDresultcheck if MF_LUdecompose was successful
MF_LUDsetEditset editing threshold for MF_LUdecompose; may be used to work around singularities
MF_LUDgetEditretrieve currently set threshold
MF_LUsolvesolve simultaneous linear equations, given the matrix in LU form
MF_LUimproveimprove the accuracy of the solution of an LU-decomposed linear system by iteration
MF_LUinvinvert matrix already composed into LU form
MF_LUdetdeterminant of matrix already composed into LU form
 
Singular Value Decomposition and related functions are offered as:
MF_SVdecompose  Singular Value Decomposition
MF_SVsolvesolve SV-decomposed set of linear equations
MF_SVDsetEditset threshold for Singular Value editing
MF_SVDgetEditretrieve current threshold for Singular Value editing

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_FFTtoCForward Fast Fourier Transform (FFT) of a real matrix; the result is a cartesian complex matrix
MF_FFTForward 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_FFTForward and backward FFT of complex matrices
MF_convolveConvolution with a spatial response function
MF_deconvolveDeconvolution
MF_filterSpatial filtering
MF_autocorrSpatial autocorrelation
MF_xcorrSpatial cross-correlation
MF_spectrumSpatial 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.
 
VF_linregress equally-weighted linear regression on X-Y data
VF_linregresswW the same with non-equal weighting
VF_polyfit fitting of one X-Y data set to a polynomial
VF_polyfitwW the same for non-equal data-point weighting
VF_linfit fitting of one X-Y data set to an arbitrary function linear in its parameters
VF_linfitwW the same for non-equal data-point weighting
VF_nonlinfit fitting of one X-Y data set to an arbitrary, possibly non-linear function
VF_nonlinfitwW the same for non-equal data-point weighting
VF_multiLinfit fitting of multiple X-Y data sets to one common linear function
VF_multiLinfitwW the same for non-equal data-point weighting
VF_multiNonlinfit fitting of multiple X-Y data sets to one common nonlinear function
VF_multiNonlinfitwW the same for non-equal data-point weighting
MF_linfitfit X-Y-Z data to a function linear in its parameters
MF_linfitwWthe same with non-equal weighting of individual data points
MF_nonlinfitfit X-Y-Z data to an arbitrary, possibly non-linear function
MF_nonlinfitwWthe same for non-equal data-point weighting
MF_multiLinfitfit multiple X-Y-Z data sets to one common linear function
MF_multiLinfitwWthe same for non-equal data-point weighting
MF_multiNonlinfitfit multiple X-Y-Z data sets to one common nonlinear function
MF_multiNonlinfitwW the same for non-equal data-point weighting
 
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: 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:
 
VF_nonlinfit_getBestValuesbest set of parameters found so far
VF_nonlinfit_getChi2the best figure-of-merit (c2, chi-square) obtained so far
VF_nonlinfit_getTestDirreturns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts (level-of-method greater than 3, see the description of VF_NONLINFITOPTIONS above)
VF_nonlinfit_getTestParindex of the parameter currently under "breakout" investigation
VF_nonlinfit_getTestRunindex of the current "breakout" test run (for each fitted parameter, one test run is performed)
VF_nonlinfit_stopstops fitting after completion of the current Levenberg-Marquardt or Downhill cycle
 
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_printprint a matrix to the screen (without paging or row cut-off); (DOS, EasyWin and Delphi only)
MF_fprintprint a matrix in ASCII format to a stream
MF_storestore in binary format
MF_recallretrieve in binary format
MF_writewrite in ASCII format in a stream
MF_readread 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_zAutoDensityMapColor 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_zDataDensityMapColor 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_setDensityBoundsSet a color scale for matrix color-density plots.
M_setDensityMapBoundsSet a color scale and draw an X-Y coordinate system for matrix color-density plots.
M_findDensityMapBoundsCalculate 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.

 
MF_addM MD_addM ME_addM
MFs_addM MDs_addM MEs_addM
MCF_addM MCD_addM MCE_addM
Functionelement-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/Delphiuses 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 );
Descriptionnormal version: MCij = MAij + MBij
scaled version: MCij = C * (MAij + MBij)
See alsoMF_addMT,   MF_subM,   MF_subrM,   chapter 9

 
MF_addMT MD_addMT ME_addMT
MFs_addMT MDs_addMT MEs_addMT
MCF_addMT MCD_addMT MCE_addMT
Functionelement-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/Delphiuses 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 );
Descriptionnormal version: MCij = MAij + MBTji
scaled version: MCij = C * (MAij + MBTji)
See alsoMF_addM,   MF_subMT,   chapter 9

 
MF_autocorr MD_autocorr ME_autocorr
FunctionSpatial 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/Delphiuses MFstd;
procedure MF_autocorr( MY, MX:fMatrix; ht, len:UInt );
DescriptionThe 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 handlingIf 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.
See alsoMF_FFT,   MF_convolve,   VF_autocorr,   chapter 12

 
MF_block_equM MD_block_equM ME_block_equM
MCF_block_equM MCD_block_equM MCE_block_equM
FunctionCopy 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/Delphiuses MFstd;
procedure MF_block_equM( MDest:fMatrix;
      destHt, destLen, firstRow, firstCol:UInt;
      MSrce:fMatrix; srceHt, srceLen:UInt );
DescriptionsMDesti+firstRow, j+firstCol = MSrcei, j,  i=0,...,srceHt-1;  j=0,...,srceLen-1
See alsoMF_block_equMT,   MF_equMblock,   MF_submatrix_equM,   chapter 5

 
MF_block_equMT MD_block_equMT ME_block_equMT
MCF_block_equMT MCD_block_equMT MCE_block_equMT
FunctionCopy 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/Delphiuses MFstd;
procedure MF_block_equMT( MDest:fMatrix;
      destHt, destLen, firstRow, firstCol:UInt;
      MSrce:fMatrix; srceHt, srceLen:UInt );
DescriptionsMDesti+firstRow, j+firstCol = MSrcej, i,  i=0,...,srceLen-1;  j=0,...,srceHt-1
See alsoMF_block_equM,   MF_equMblockT,   MF_submatrix_equM,   chapter 5

 

M_CDtoCFM_CDtoCE
M_CEtoCFM_CEtoCD
M_CFtoCDM_CFtoCE
FunctionData type conversions. See M_FtoD.

 
MF_Col_addC MD_Col_addC ME_Col_addC
MCF_Col_addC MCD_Col_addC MCE_Col_addC
Functionadd 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/Delphiuses MFstd;
procedure MF_Col_addC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
DescriptionMAi,iCol += C,  i=0,...,ht-1
See alsoMF_Col_subC,   MF_Row_addC,   MF_Col_addV,   chapter 6

 
MF_Col_addV MD_Col_addV ME_Col_addV
MCF_Col_addV MCD_Col_addV MCE_Col_addV
Functionadd 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/Delphiuses MFstd;
procedure MF_Col_addV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
DescriptionMAi,iCol += Xi,  i=0,...,ht-1
See alsoMF_Col_subV,   MF_Row_addV,   MF_Col_addC,   chapter 6

 
MF_Col_delete MD_Col_delete ME_Col_delete
MCF_Col_delete MCD_Col_delete MCE_Col_delete
Functiondelete 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/Delphiuses MFstd;
procedure MF_Col_delete( MB, MA:fMatrix; htA, lenA, iCol:UInt );
DescriptionMBi,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
See alsoMF_Col_insert,   MF_Row_delete,   VF_delete,   chapter 5

 
MF_Col_divC MD_Col_divC ME_Col_divC
MCF_Col_divC MCD_Col_divC MCE_Col_divC
Functiondivide 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/Delphiuses MFstd;
procedure MF_Col_divC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
DescriptionMAi,iCol /= C,  i=0,...,ht-1
See alsoMF_Col_divrC,   MF_Row_divC,   MF_Col_mulC,   chapter 6

 
MF_Col_divrC MD_Col_divrC ME_Col_divrC
MCF_Col_divrC MCD_Col_divrC MCE_Col_divrC
FunctionReverse 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/Delphiuses MFstd;
procedure MF_Col_divrC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
DescriptionMAi,iCol = C / MAi,iCol,  i=0,...,ht-1
See alsoMF_Col_divC,   MF_Row_divrC,   MF_Col_divV,   chapter 6

 
MF_Col_divrV MD_Col_divrV ME_Col_divrV
MCF_Col_divrV MCD_Col_divrV MCE_Col_divrV
FunctionReverse 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/Delphiuses MFstd;
procedure MF_Col_divrV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
DescriptionMAi,iCol = Xi / MAi,iCol,  i=0,...,ht-1
See alsoMF_Col_divV,   MF_Row_divrV,   MF_Col_divrC,   chapter 6

 
MF_Col_divV MD_Col_divV ME_Col_divV
MCF_Col_divV MCD_Col_divV MCE_Col_divV
Functionelement-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/Delphiuses MFstd;
procedure MF_Col_divV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
DescriptionMAi,iCol /= Xi,  i=0,...,ht-1
See alsoMF_Col_divrV,   MF_Row_divV,   MF_Col_divC,   chapter 6

 
MF_Col_equ0 MD_Col_equ0 ME_Col_equ0
MCF_Col_equ0 MCD_Col_equ0 MCE_Col_equ0
Functionset 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/Delphiuses MFstd;
procedure MF_Col_equ0( MA:fMatrix; ht, len, iCol:UInt );
DescriptionMAi,iCol = 0,  i=0,...,ht-1
See alsoMF_Col_equC,   MF_Row_equ0,   MF_Dia_equ0,   chapter 6

 
MF_Col_equC MD_Col_equC ME_Col_equC
MCF_Col_equC MCD_Col_equC MCE_Col_equC
Functioninitialize 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/Delphiuses MFstd;
procedure MF_Col_equC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
DescriptionMAi,iCol = C,  i=0,...,ht-1
See alsoMF_Col_equV,   MF_Row_equC,   MF_Dia_equC,   chapter 6

 
MF_Col_equV MD_Col_equV ME_Col_equV
MCF_Col_equV MCD_Col_equV MCE_Col_equV
Functioncopy 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/Delphiuses MFstd;
procedure MF_Col_equV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
DescriptionMAi,iCol = Xi,  i=0,...,ht-1
See alsoMF_Col_equ0,   MF_Row_equV,   MF_Dia_equV,   chapter 6

 
MF_Col_extract MD_Col_extract ME_Col_extract
MCF_Col_extract MCD_Col_extract MCE_Col_extract
Functioncopy 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/Delphiuses MFstd;
procedure MF_Col_extract( Y:fVector; MA:fMatrix; ht, len, iCol:UInt );
DescriptionYi = MAi,iCol,  i=0,...,ht-1
See alsoMF_Row_extract,   MF_Dia_extract,   MF_Col_equV,   chapter 3

 
MF_Col_insert MD_Col_insert ME_Col_insert
MCF_Col_insert MCD_Col_insert MCE_Col_insert
Functionaugment 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/Delphiuses MFstd;
procedure MF_Col_insert( MB, MA:fMatrix; htB, lenB, iCol:UInt; X:fVector );
DescriptionMBi,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
See alsoMF_Col_delete,   chapter 5

 
MF_Col_mulC MD_Col_mulC ME_Col_mulC
MCF_Col_mulC MCD_Col_mulC MCE_Col_mulC
Functionmultiply 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/Delphiuses MFstd;
procedure MF_Col_mulC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
DescriptionMAi,iCol *= C,  i=0,...,ht-1
See alsoMF_Col_divC,   MF_Row_divC,   MF_Col_mulV,   chapter 6

 
MF_Col_mulV MD_Col_mulV ME_Col_mulV
MCF_Col_mulV MCD_Col_mulV MCE_Col_mulV
Functionelement-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/Delphiuses MFstd;
procedure MF_Col_mulV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
DescriptionMAi,iCol *= Xi,  i=0,..,ht-1
See alsoMF_Col_divV,   MF_Row_divV,   MF_Col_mulC,   chapter 6

 
MF_Col_subC MD_Col_subC ME_Col_subC
MCF_Col_subC MCD_Col_subC MCE_Col_subC
Functionsubtract 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/Delphiuses MFstd;
procedure MF_Col_subC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
DescriptionMAi,iCol -= C,  i=0,..,ht-1
See alsoMF_Col_addC,   MF_Row_subC,   MF_Col_subV,   MF_Col_subrC,   chapter 6

 
MF_Col_subrC MD_Col_subrC ME_Col_subrC
MCF_Col_subrC MCD_Col_subrC MCE_Col_subrC
Functionreverse 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/Delphiuses MFstd;
procedure MF_Col_subrC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
DescriptionMAi,iCol = C - MAi,iCol,  i=0,..,ht-1
See alsoMF_Col_addC,   MF_Row_subC,   MF_Col_subrV,   MF_Col_subC,   chapter 6

 
MF_Col_subrV MD_Col_subrV ME_Col_subrV
MCF_Col_subrV MCD_Col_subrV MCE_Col_subrV
Functionreverse 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/Delphiuses MFstd;
procedure MF_Col_subrV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
DescriptionMAi,iCol = Xi - MAi,iCol,  i=0,..,ht-1
See alsoMF_Col_subV,   MF_Row_subrV,   MF_Col_subrC,   chapter 6

 
MF_Col_subV MD_Col_subV ME_Col_subV
MCF_Col_subV MCD_Col_subV MCE_Col_subV
Functionsubtract 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/Delphiuses MFstd;
procedure MF_Col_subV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
DescriptionMAi,iCol -= Xi,  i=0,..,ht-1
See alsoMF_Col_subC,   MF_Row_subV,   MF_Col_subrC,   chapter 6

 
MF_Cols_absmax MD_Cols_absmax ME_Cols_absmax
MCF_Cols_absmax MCD_Cols_absmax MCE_Cols_absmax
Functionstore 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/Delphiuses MFstd;
procedure MF_Cols_absmax( Y:fVector; MA:fMatrix; ht, len:UInt );
procedure MCF_Cols_absmax( Y:fVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe maximum absolute value of each column j is stored as the element Yj for j=0,..,len-1
See alsoMF_Cols_max,   MF_Cols_absmin,   MF_Rows_absmax,   MF_Dia_absmax,   chapter 7

 
MCF_Cols_absmaxReIm MCD_Cols_absmaxReIm MCE_Cols_absmaxReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Cols_absmaxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe maximum absolute values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1
See alsoMCF_Cols_absmax,   MCF_Cols_minReIm,   MCF_Rows_absmaxReIm,   chapter 7

 
MF_Cols_absmin MD_Cols_absmin ME_Cols_absmin
MCF_Cols_absmin MCD_Cols_absmin MCE_Cols_absmin
Functionstore 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/Delphiuses MFstd;
procedure MF_Cols_absmin( Y:fVector; MA:fMatrix; ht, len:UInt );
procedure MCF_Cols_absmin( Y:fVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe minimum absolute value of each column j is stored as the element Yj for j=0,..,len-1
See alsoMF_Cols_min,   MF_Cols_absmax,   MF_Rows_absmin,   MF_Dia_absmin,   chapter 7

 
MCF_Cols_absminReIm MCD_Cols_absminReIm MCE_Cols_absminReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Cols_absminReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe minimum absolute values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1
See alsoMCF_Cols_absmin,   MCF_Cols_minReIm,   MCF_Rows_absminReIm,   chapter 7

 
MF_Cols_add MD_Cols_add ME_Cols_add
MCF_Cols_add MCD_Cols_add MCE_Cols_add
Functionmake 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/Delphiuses MFstd;
procedure MF_Cols_add( MA:fMatrix; ht, len, destCol, sourceCol:UInt );
DescriptionMAi,destCol += MAi,sourceCol,  i=0,..,ht-1
See alsoMF_Cols_sub,   MF_Cols_Cadd,   MF_Cols_lincomb,   chapter 8

 
MCF_Cols_cabsmax MCD_Cols_cabsmax MCE_Cols_cabsmax
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Cols_cabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Cols_absmax,   MCF_Cols_cabsmin,   MCF_Cols_sabsmax,   MCF_Rows_cabsmax,   MCF_Dia_cabsmax,   chapter 7

 
MCF_Cols_cabsmin MCD_Cols_cabsmin MCE_Cols_cabsmin
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Cols_cabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Cols_absmin,   MCF_Cols_cabsmax,   MCF_Cols_sabsmin,   MCF_Rows_cabsmin,   MCF_Dia_cabsmin,   chapter 7

 
MF_Cols_Cadd MD_Cols_Cadd ME_Cols_Cadd
MCF_Cols_Cadd MCD_Cols_Cadd MCE_Cols_Cadd
Functionmake 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/Delphiuses MFstd;
procedure MF_Cols_Cadd( MA:fMatrix; ht, len, destCol, sourceCol:UInt; C:Single );
DescriptionMAi,destCol += C * MAi,sourceCol,  i=0,..,ht-1
See alsoMF_Cols_add,   MF_Cols_lincomb,   chapter 8

 
MF_Cols_exchange MD_Cols_exchange ME_Cols_exchange
MCF_Cols_exchange MCD_Cols_exchange MCE_Cols_exchange
Functionexchange 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/Delphiuses MFstd;
procedure MF_Cols_exchange( MA:fMatrix; ht, len, i1, i2:UInt );
DescriptionThe elements of the columns i1 and i2 are exchanged.
See alsoMF_Rows_exchange,   chapter 8

 
MF_Cols_lincomb MD_Cols_lincomb ME_Cols_lincomb
MCF_Cols_lincomb MCD_Cols_lincomb MCE_Cols_lincomb
Functionlinear 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/Delphiuses MFstd;
procedure MF_Cols_lincomb( MA:fMatrix; ht, len:UInt; destCol:UInt; destC:Single; srceCol:Uint; srceC:Single );
DescriptionMAi,destCol = destC * MAi,destCol+ srceC * MAi,srceCol,  i=0,..,ht-1
See alsoMF_Cols_add,   MF_Cols_Cadd,   chapter 8

 
MF_Cols_max MD_Cols_max ME_Cols_max
MCF_Cols_max MCD_Cols_max MCE_Cols_max
Functionstore 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/Delphiuses MFstd;
procedure MF_Cols_max( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionThe maximum value of each column j is stored as the element Yj for j=0,..,len-1
See alsoMF_Cols_absmax,   MF_Cols_min,   MF_Rows_max,   chapter 7

 
MCF_Cols_maxReIm MCD_Cols_maxReIm MCE_Cols_maxReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Cols_maxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe maximum values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1
See alsoMCF_Cols_absmax,   MCF_Cols_minReIm,   MCF_Rows_absmaxReIm,   chapter 7

 
MF_Cols_min MD_Cols_min ME_Cols_min
MCF_Cols_min MCD_Cols_min MCE_Cols_min
Functionstore 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/Delphiuses MFstd;
procedure MF_Cols_min( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionThe minimum value of each column j is stored as the element Yj for j=0,..,len-1
See alsoMF_Cols_absmax,   MF_Cols_min,   MF_Rows_max,   chapter 7

 
MCF_Cols_minReIm MCD_Cols_maxReIm MCE_Cols_maxReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Cols_minReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe maximum values of the real and imaginary parts of each column j are combined into the element Yj for j=0,..,len-1
See alsoMCF_Cols_absmin,   MCF_Cols_maxReIm,   MCF_Rows_absminReIm,   chapter 7

 
MF_Cols_prod MD_Cols_prod ME_Cols_prod
MCF_Cols_prod MCD_Cols_prod MCE_Cols_prod
Functionproducts 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/Delphiuses MFstd;
procedure MF_Cols_prod(Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionYj = prod( MAi,j, i=0,..,ht-1),  j=0,..,len-1
See alsoMF_Cols_runprod,   MF_Cols_sum,   chapter 7

 
MF_Cols_reflect MD_Cols_reflect ME_Cols_reflect
FunctionDerive 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/Delphiuses MFstd;
procedure MF_Cols_reflect( MA:fMatrix; ht, len:UInt );
DescriptionMAht-i-1,j = MAi, j,  i=0,..(ht-1)/2;  j=0,..,len-1
See alsoMF_Cols_rotate,   MF_Rows_reflect,   chapter 7

 
MF_Cols_rotate MD_Cols_rotate ME_Cols_rotate
MCF_Cols_rotate MCD_Cols_rotate MCE_Cols_rotate
Functionrotate 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/Delphiuses MFstd;
procedure MF_Cols_rotate( MA:fMatrix; ht, len:UInt; pos:Integer );
DescriptionMAi,j = MAht-pos+i, j,   i=0,..,pos-1
MAi,j = MAi-pos, j,      i=pos,...,ht-1
See alsoMF_Cols_reflect,   MF_Rows_rotate,   chapter 7

 
MF_Cols_runprod MD_Cols_runprod ME_Cols_runprod
MCF_Cols_runprod MCD_Cols_runprod MCE_Cols_runprod
Functionrunning 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/Delphiuses MFstd;
procedure MF_Cols_runprod( MA:fMatrix; ht, len:UInt );
DescriptionFor 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.
See alsoMF_Cols_prod,   MF_Rows_runprod,   chapter 7

 
MF_Cols_runsum MD_Cols_runsum ME_Cols_runsum
MCF_Cols_runsum MCD_Cols_runsum MCE_Cols_runsum
Functionrunning 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/Delphiuses MFstd;
procedure MF_Cols_runsum( MA:fMatrix; ht, len:UInt );
DescriptionFor all columns separately, each element is the sum of itself and all preceding elements.
See alsoMF_Cols_sum,   MF_Rows_runsum,   chapter 7

 
MCF_Cols_sabsmax MCD_Cols_sabsmax MCE_Cols_sabsmax
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Cols_sabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Cols_absmax,   MCF_Cols_cabsmin,   MCF_Cols_sabsmax,   MCF_Rows_cabsmax,   MCF_Dia_cabsmax,   chapter 7

 
MCF_Cols_sabsmin MCD_Cols_sabsmin MCE_Cols_sabsmin
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Cols_sabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Cols_absmin,   MCF_Cols_cabsmax,   MCF_Cols_sabsmin,   MCF_Rows_cabsmin,   MCF_Dia_cabsmin,   chapter 7

 
MF_Cols_sub MD_Cols_sub ME_Cols_sub
MCF_Cols_sub MCD_Cols_sub MCE_Cols_sub
Functionsubtract 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/Delphiuses MFstd;
procedure MF_Cols_sub( MA:fMatrix; ht, len, destCol, sourceCol:UInt; );
DescriptionMAi,destCol -= MAi,sourceCol,  i=0,..,ht-1
See alsoMF_Cols_add,   MF_Cols_Cadd,   chapter 8

 
MF_Cols_sum MD_Cols_sum ME_Cols_sum
MCF_Cols_sum MCD_Cols_sum MCE_Cols_sum
Functionsums 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/Delphiuses MFstd;
procedure MF_Cols_sum( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionYj = sum( MAi,j, i=0,..,ht-1),  j=0,..,len-1
See alsoMF_Cols_prod,   MF_Cols_runsum,   chapter 7

 
MCF_conj MCD_conj MCE_conj
Functioncomplex 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/Delphiuses MFstd;
procedure MCF_conj( MB, MA:cfMatrix; ht, len:UInt );
DescriptionMBij.Re = MAij.Re
MBij.Im = -MAij.Im
See alsoMCF_neg,   chapter 3

 
MF_convolve MD_convolve ME_convolve
Functionconvolution 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/Delphiuses 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 handlingIf 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.
See alsoMF_deconvolve,   MF_FFT,   chapter 12

 
MF_cprint MD_cprint ME_cprint
MCF_cprint MCD_cprint MCE_cprint
Functionprint 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/Delphiuses MFstd;
procedure MF_cprint( MA:fMatrix; ht, len:UInt );
DescriptionThe 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 handlingIf 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.
See alsoMF_fprint,   VF_cprint,   chapter 14

 
MF_deconvolve MD_deconvolve ME_deconvolve
Functionspatial 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/Delphiuses MFstd;
procedure MF_deconvolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UInt );
DescriptionMX 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 handlingIf 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.
See alsoMF_convolve,   MF_FFT,   chapter 12

 
MF_det MD_det ME_det
MCF_det MCD_det MCE_det
Functiondeterminant 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/Delphiuses MFstd;
function MF_det( MA:fMatrix; len:UInt ):Single;
DescriptionThe determinant of MA is calculated. For large matrices, this is done via LU decomposition. For small matrices, individual formulae are applied.
Return valuedeterminant of the matrix
See alsoMF_LUdecompose,   MF_solve,   chapter 10

 
MF_Dia_absmax MD_Dia_absmax ME_Dia_absmax
MCF_Dia_absmax MCD_Dia_absmax MCE_Dia_absmax
Functionabsolute 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/Delphiuses MFstd;
function MF_Dia_absmax( MA:fMatrix; len:UInt ):Single;
DescriptionThe maximum absolute value of all elements MAi,i is returned as a scalar
Return valueabsolute maximum of the diagonal
See alsoMF_Dia_max,   MF_Dia_absmin,   chapter 7

 
MCF_Dia_absmaxReIm MCD_Dia_absmaxReIm MCE_Dia_absmaxReIm
FunctionSeparate 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/Delphiuses MCFstd;
procedure MCF_Dia_absmaxReIm( var Max:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe 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).
See alsoMCF_Dia_absminReIm,   MCF_Dia_absmax,   MCF_Dia_maxReIm,   MCF_Rows_absmaxReIm,   chapter 7

 
MF_Dia_absmin MD_Dia_absmin ME_Dia_absmin
MCF_Dia_absmin MCD_Dia_absmin MCE_Dia_absmin
Functionabsolute 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/Delphiuses MFstd;
function MF_Dia_absmin( MA:fMatrix; len:UInt ):Single;
DescriptionThe minimum absolute value of all elements MAi,i is returned as a scalar
Return valueabsolute minimum of the diagonal
See alsoMF_Dia_min,   MF_Dia_absmax,   chapter 7

 
MCF_Dia_absminReIm MCD_Dia_absminReIm MCE_Dia_absminReIm
FunctionSeparate 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/Delphiuses MCFstd;
procedure MCF_Dia_absminReIm( var Min:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe 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).
See alsoMCF_Dia_absmaxReIm,   MCF_Dia_absmin,   MCF_Dia_minReIm,   MCF_Rows_absmaxReIm,   chapter 7

 
MF_Dia_addC MD_Dia_addC ME_Dia_addC
MCF_Dia_addC MCD_Dia_addC MCE_Dia_addC
Functionadd 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/Delphiuses MFstd;
procedure MF_Dia_addC( MA:fMatrix; len:UInt; C:Single );
DescriptionMAi,i += C,  i=0,...,len-1
See alsoMF_Dia_addV,   MF_Dia_subC,   chapter 6

 
MF_Dia_addV MD_Dia_addV ME_Dia_addV
MCF_Dia_addV MCD_Dia_addV MCE_Dia_addV
Functionelement-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/Delphiuses MFstd;
procedure MF_Dia_addV( MA:fMatrix; len:UInt; X:fVector );
DescriptionMAi,i += Xi,  i=0,...,len-1
See alsoMF_Dia_addC,   MF_Dia_subV,   chapter 6

 
MCF_Dia_cabsmax MCD_Dia_cabsmax MCE_Dia_cabsmax
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Dia_cabsmax( var Max:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe complex number of largest magnitude, sqrt(Re2+Im2), is found.
See alsoMCF_Dia_cabsmin,   MCF_Dia_absmax,   MCF_Dia_maxReIm,   MCF_Rows_cabsmax,   chapter 7

 
MCF_Dia_cabsmin MCD_Dia_cabsmin MCE_Dia_cabsmin
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Dia_cabsmin( var Max:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe complex number of smallest magnitude, sqrt(Re2+Im2), is found.
See alsoMCF_Dia_cabsmax,   MCF_Dia_absmin,   MCF_Dia_minReIm,   MCF_Rows_cabsmin,   chapter 7

 
MF_Dia_divC MD_Dia_divC ME_Dia_divC
MCF_Dia_divC MCD_Dia_divC MCE_Dia_divC
Functiondivide 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/Delphiuses MFstd;
procedure MF_Dia_divC( MA:fMatrix; len:UInt; C:Single );
DescriptionMAi,i /= C,  i=0,...,len-1
See alsoMF_Dia_divV,   MF_Dia_mulC,   MF_Dia_divrC,   chapter 6

 
MF_Dia_divrC MD_Dia_divrC ME_Dia_divrC
MCF_Dia_divrC MCD_Dia_divrC MCE_Dia_divrC
Functionreverse 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/Delphiuses MFstd;
procedure MF_Dia_divrC( MA:fMatrix; len:UInt; C:Single );
DescriptionMAi,i = C / MAi,i,  i=0,...,len-1
See alsoMF_Dia_divrV,   MF_Dia_mulC,   MF_Dia_divC,   chapter 6

 
MF_Dia_divrV MD_Dia_divrV ME_Dia_divrV
MCF_Dia_divrV MCD_Dia_divrV MCE_Dia_divrV
Functionreverse 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/Delphiuses MFstd;
procedure MF_Dia_divrV( MA:fMatrix; len:UInt; X:fVector );
DescriptionMAi,i = Xi / MAi,i,  i=0,...,len-1
See alsoMF_Dia_divV,   MF_Dia_mulV,   MF_Dia_divrC,   chapter 6

 
MF_Dia_divV MD_Dia_divV ME_Dia_divV
MCF_Dia_divV MCD_Dia_divV MCE_Dia_divV
Functionelement-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/Delphiuses MFstd;
procedure MF_Dia_divV( MA:fMatrix; len:UInt; X:fVector );
DescriptionMAi,i / Xi,  i=0,...,len-1
See alsoMF_Dia_divrV,   MF_Dia_mulV,   MF_Dia_divC,   chapter 6

 
MF_Dia_equ0 MD_Dia_equ0 ME_Dia_equ0
MCF_Dia_equ0 MCD_Dia_equ0 MCE_Dia_equ0
Functioninitialize 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/Delphiuses MFstd;
procedure MF_Dia_equ0( MA:fMatrix; len:UInt );
DescriptionMAi,i = 0,  i=0,...,len-1
See alsoMF_Dia_equC,   MF_Dia_equV,   chapter 3,   chapter 6,   chapter 7

 
MF_Dia_equC MD_Dia_equC ME_Dia_equC
MCF_Dia_equC MCD_Dia_equC MCE_Dia_equC
Functioninitialize 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/Delphiuses MFstd;
procedure MF_Dia_equC( MA:fMatrix; len:UInt; C:Single );
DescriptionMAi,i = C,  i=0,...,len-1
See alsoMF_Dia_equ0,   MF_Dia_equV,   chapter 3,   chapter 6,   chapter 7

 
MF_Dia_equV MD_Dia_equV ME_Dia_equV
MCF_Dia_equV MCD_Dia_equV MCE_Dia_equV
Functioncopy 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/Delphiuses MFstd;
procedure MF_Dia_equV( MA:fMatrix; len:UInt; X:fVector );
DescriptionMAi,i = Xi,  i=0,...,len-1
See alsoMF_Dia_equ0,   MF_Dia_equC,   chapter 3,   chapter 6,   chapter 7

 
MF_Dia_extract MD_Dia_extract ME_Dia_extract
MCF_Dia_extract MCD_Dia_extract MCE_Dia_extract
Functioncopy 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/Delphiuses MFstd;
procedure MF_Dia_extract( Y:fVector; MA:fMatrix; len:UInt );
DescriptionYi = MAi,i,  i=0,...,len-1
See alsoMF_Dia_equV,   chapter 3,   chapter 6

 
MF_Dia_max MD_Dia_max ME_Dia_max
MCF_Dia_max MCD_Dia_max MCE_Dia_max
Functionmaximum 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/Delphiuses MFstd;
function MF_Dia_max( MA:fMatrix; len:UInt ):Single;
Descriptionthe largest element of the diagonal is returned as a scalar
Return valuemaximum of the diagonal
See alsoMF_Dia_absmax,   MF_Dia_min,   chapter 6,   chapter 7

 
MCF_Dia_maxReIm MCD_Dia_maxReIm MCE_Dia_maxReIm
FunctionSeparate 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/Delphiuses MCFstd;
procedure MCF_Dia_maxReIm( var Max:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe 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).
See alsoMCF_Dia_minReIm,   MCF_Dia_max,   MCF_Dia_absmaxReIm,   MCF_Rows_maxReIm,   chapter 7

 
MF_Dia_min MD_Dia_min ME_Dia_min
MCF_Dia_min MCD_Dia_min MCE_Dia_min
Functionminimum 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/Delphiuses MFstd;
function MF_Dia_min( MA:fMatrix; len:UInt ):Single;
Descriptionthe smallest or most negative element of the diagonal is returned as a scalar
Return valueminimum of the diagonal
See alsoMF_Dia_absmin,   MF_Dia_max,   chapter 6,   chapter 7

 
MCF_Dia_minReIm MCD_Dia_minReIm MCE_Dia_minReIm
FunctionSeparate 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/Delphiuses MCFstd;
procedure MCF_Dia_minReIm( var Min:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe 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).
See alsoMCF_Dia_maxReIm,   MCF_Dia_min,   MCF_Dia_absminReIm,   MCF_Rows_absminReIm,   chapter 7

 
MF_Dia_mulC MD_Dia_mulC ME_Dia_mulC
MCF_Dia_mulC MCD_Dia_mulC MCE_Dia_mulC
Functionmultiply 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/Delphiuses MFstd;
procedure MF_Dia_mulC( MA:fMatrix; len:UInt; C:Single );
DescriptionMAi,i *= C,  i=0,...,len-1
See alsoMF_Dia_mulV,   MF_Dia_divC,   chapter 6

 
MF_Dia_mulV MD_Dia_mulV ME_Dia_mulV
MCF_Dia_mulV MCD_Dia_mulV MCE_Dia_mulV
Functionelement-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/Delphiuses MFstd;
procedure MF_Dia_mulV( MA:fMatrix; len:UInt; X:fVector );
DescriptionMAi,i *= Xi,  i=0,...,len-1
See alsoMF_Dia_mulC,   MF_Dia_divV,   chapter 6

 
MF_Dia_prod MD_Dia_prod ME_Dia_prod
MCF_Dia_prod MCD_Dia_prod MCE_Dia_prod
Functionproduct 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/Delphiuses MFstd;
function MF_Dia_prod( MA:fMatrix; len:UInt ):Single;
Descriptionthe product of the diagonal elements is returned as a scalar
Return valueproduct of the diagonal elements
See alsoMF_Dia_sum,   chapter 7

 
MCF_Dia_sabsmax MCD_Dia_sabsmax MCE_Dia_sabsmax
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Dia_sabsmax( var Max:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe complex number of largest sum |Re| + |Im|, is found.
See alsoMCF_Dia_sabsmin,   MCF_Dia_absmax,   MCF_Dia_maxReIm,   MCF_Rows_sabsmax,   chapter 7

 
MCF_Dia_sabsmin MCD_Dia_sabsmin MCE_Dia_sabsmin
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Dia_sabsmin( var Max:fComplex; MA:cfMatrix; len:UInt );
DescriptionThe complex number with the smallest sum |Re| + |Im| is found.
See alsoMCF_Dia_sabsmax,   MCF_Dia_absmin,   MCF_Dia_minReIm,   MCF_Rows_sabsmin,   chapter 7

 
MF_Dia_subC MD_Dia_subC ME_Dia_subC
MCF_Dia_subC MCD_Dia_subC MCE_Dia_subC
Functionsubtract 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/Delphiuses MFstd;
procedure MF_Dia_subC( MA:fMatrix; len:UInt; C:Single );
DescriptionMAi,i -= C,  i=0,...,len-1
See alsoMF_Dia_subV,   MF_Dia_subrC,   chapter 6

 
MF_Dia_subrC MD_Dia_subrC ME_Dia_subrC
MCF_Dia_subrC MCD_Dia_subrC MCE_Dia_subrC
Functionreverse 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/Delphiuses MFstd;
procedure MF_Dia_subrC( MA:fMatrix; len:UInt; C:Single );
DescriptionMAi,i = C - MAi,i,  i=0,...,len-1
See alsoMF_Dia_subrV,   MF_Dia_subC,   chapter 6

 
MF_Dia_subrV MD_Dia_subrV ME_Dia_subrV
MCF_Dia_subrV MCD_Dia_subrV MCE_Dia_subrV
Functionreverse 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/Delphiuses MFstd;
procedure MF_Dia_subrV( MA:fMatrix; len:UInt; X:fVector );
DescriptionMAi,i = Xi - MAi,i,  i=0,...,len-1
See alsoMF_Dia_subV,   MF_Dia_subrC,   chapter 6

 
MF_Dia_subV MD_Dia_subV ME_Dia_subV
MCF_Dia_subV MCD_Dia_subV MCE_Dia_subV
Functionelement-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/Delphiuses MFstd;
procedure MF_Dia_subV( MA:fMatrix; len:UInt; X:fVector );
DescriptionMAi,i -= Xi,  i=0,...,len-1
See alsoMF_Dia_subrV,   MF_Dia_subC,   chapter 6

 
MF_Dia_sum MD_Dia_sum ME_Dia_sum
MCF_Dia_sum MCD_Dia_sum MCE_Dia_sum
Functionsum 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/Delphiuses MFstd;
function MF_Dia_sum( MA:fMatrix; len:UInt ):Single;
Descriptionthe elements of the diagonal are summed up and returned as a scalar
Return valuesum over the diagonal elements
See alsoMF_Dia_prod,   chapter 7

 
MF_divC MD_divC ME_divC
MCF_divC MCD_divC MCE_divC
MCF_divReC MCD_divReC MCE_divReC
Functiondivide 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/Delphiuses MFstd;
procedure MF_divC( MB, MA:fMatrix; ht, len:UInt; C:Single );
DescriptionMi,j /= C,  i=0,...,ht-1;  j=0,..,len-1
See alsoMF_mulC,   chapter 3

 
M_DtoFM_DtoE
FunctionData type conversions. See M_FtoD.

 
MF_element MD_element ME_element
MCF_element MCD_element MCE_element
Functionread-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/Delphiuses MFstd;
function MF_element( MA:fMatrix; ht, len, m, n:UInt );
procedure MCF_element( var RetVal:fComplex; MA:cfMatrix; ht, len, m, n:UInt );
DescriptionThe 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 valuethe matrix element m,n (except complex version in Pascal/Delphi)
See alsoMF_Pelement,   chapter 2

 
MFsym_eigenvalues MDsym_eigenvalues MEsym_eigenvalues
FunctionEigenvalues 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/Delphiuses MFstd;
procedure MFsym_eigenvalues( EigVals:fVector; EigVecs, MA:fMatrix; len:UInt; CalcEigenVec:IntBool );
DescriptionThe 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.
See alsochapter 10,   chapter 11

 
MF_equ0 MD_equ0 ME_equ0
MCF_equ0 MCD_equ0 MCE_equ0
Functioninitialize 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/Delphiuses MFstd;
procedure MF_equ0( MA:fMatrix; ht, len:UInt );
DescriptionMAi,j = 0
See alsoMF_equ1,   MF_equM,   chapter 3

 
MF_equ1 MD_equ1 ME_equ1
MCF_equ1 MCD_equ1 MCE_equ1
Functionidentity matrix
Syntax C/C++#include <MFstd.h>
void MF_equ1( fMatrix A, unsigned len );
C++ MatObj#include <OptiVec.h>
void matrix<T>::equ1( );
Pascal/Delphiuses MFstd;
procedure MF_equ1( MA:fMatrix; len:UInt );
DescriptionMAi,i = 1
MAi,j = 0,  i != j
See alsoMF_equ0,   MF_equm1,   chapter 3

 
MF_equM MD_equM ME_equM
MCF_equM MCD_equM MCE_equM
Functionmake 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/Delphiuses MFstd;
procedure MF_equM( MB, MA:fMatrix; ht, len:UInt );
DescriptionMBi,j = MAi,j
See alsoMF_transpose,   MF_neg,   chapter 3

 
MF_equm1 MD_equm1 ME_equm1
MCF_equm1 MCD_equm1 MCE_equm1
Functionnegative 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/Delphiuses MFstd;
procedure MF_equm1( MA:fMatrix; len:UInt );
DescriptionMAi,i = -1
MAi,j = 0,  i != j
See alsoMF_equ0,   MF_equ1,   chapter 3

 
MF_equMblock MD_equMblock ME_equMblock
MCF_equMblock MCD_equMblock MCE_equMblock
FunctionExtract 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/Delphiuses MFstd;
procedure MF_equMblock( MSub:fMatrix;
      subHt, subLen: UInt;
      MSrce:fMatrix;
      srceHt, srceLen, firstRow, firstCol:UInt );
DescriptionMSubi, j = MSrcei+firstRow, j+firstCol,  i=0,...,subHt-1;  j=0,...,subLen-1
See alsoMF_block_equM,   MF_equMblockT,   MF_submatrix_equM,   chapter 5

 
MF_equMblockT MD_equMblockT ME_equMblockT
MCF_equMblockT MCD_equMblockT MCE_equMblockT
FunctionExtract 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/Delphiuses MFstd;
procedure MF_equMblockT( MSub:fMatrix;
      subHt, subLen: UInt;
      MSrce:fMatrix;
      srceHt, srceLen, firstRow, firstCol:UInt );
DescriptionMSubj, i = MSrcei+firstRow, j+firstCol,  i=0,...,subLen-1;  j=0,...,subHt-1
See alsoMF_block_equMT,   MF_equMblock,   MF_submatrix_equM,   chapter 5

 
MF_FFT MD_FFT ME_FFT
MF_FFTtoC MD_FFTtoC ME_FFTtoC
MCF_FFT MCD_FFT MCE_FFT
Functiontwo-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/Delphiuses 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 );
DescriptionThe 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.ReU0,len/2.ReU0,1.ReU0,1.Im···U0,len/2-1.ReU0,len/2-1.Im
Uht/2,0.ReUht/2,len/2.ReU1,1.ReU1,1.Im···U1,len/2-1.ReU1,len/2-1.Im
U1,0.ReU1,len/2.ReU2,1.ReU2,1.Im···U2,len/2-1.ReU2,len/2-1.Im
U1,0.ImU1,len/2.ImU3,1.ReU3,1.Im···U3,len/2-1.ReU3,len/2-1.Im
·····················
Uht/2-1,0.ReUht/2-1,len/2.Re···············
Uht/2-1,0.ImUht/2-1,len/2.ImUht-1,1.ReUht-1,1.Im···Uht-1,len/2-1.ReUht-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 handlingIf 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.
See alsochapter 12,   chapter 4.8 of HANDBOOK.HTM

 
MF_filter MD_filter ME_filter
MCF_filter MCD_filter MCE_filter
FunctionSpatial 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/Delphiuses MFstd;
procedure MF_filter( MY, MX, MFlt:fMatrix; ht, len:UInt );
DescriptionA 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 handlingIf 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.
See alsoMF_FFT,   MF_convolve,   chapter 12,   chapter 4.8 of HANDBOOK.HTM

 
M_findDensityMapBounds
FunctionCalculate 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/Delphiuses Mgraph;
procedure M_findDensityMapBounds( xmin, xmax, ymin, ymax, zmin, zmax: Extended; mincolor, maxcolor: COLORREF );
DescriptionSimilarly 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.

See alsoMF_xyzAutoDensityMap,   MF_zAutoDensityMap,   chapter 15

 
MF_fprint MD_fprint ME_fprint
MCF_fprint MCD_fprint MCE_fprint
Functionprint 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/Delphiuses 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 );
DescriptionThe 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 handlingif 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.
See alsoMF_cprint,   chapter 14

 
M_free
Functionde-allocate a matrix
Syntax C/C++#include <MFstd.h>
void M_free( void **M );
C++ MatObj#include <OptiVec.h>
void matrix<T>::free();
Pascal/Delphiuses MFstd;
procedure M_free( M:Pointer );
DescriptionThe 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 handlingTrying 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.
See alsoM_nfree,  V_freeAll,  MF_matrix,  MF_matrix0

 
M_FtoDM_FtoEM_CFtoCDM_CFtoCE
M_DtoFM_DtoEM_CDtoCFM_CDtoCE
M_EtoFM_EtoDM_CEtoCFM_CEtoCD
FunctionData 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/Delphiuses 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)
DescriptionEach element of MX is converted from the data type specified for MX to the data type specified for MY and stored in MY.
Error handlingOVERFLOW 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.
See alsochapter 4

 
VF_getLinfitNeglect VD_getLinfitNeglect VE_getLinfitNeglect
Functionretrieve 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/Delphiuses MFstd;
function VF_getLinfitNeglect:Single;
DescriptionInternally, 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 valuecurrent significance threshold for linear fitting
See alsoVF_linfit,   VF_multiLinfit,   chapter 13.2

 
VF_getNonlinfitOptions VD_getNonlinfitOptions VE_getNonlinfitOptions
Functionretrieve current set of options for nonlinear fitting
Syntax C/C++#include <MFstd.h>
void VF_getNonlinfitOptions( VF_NONLINFITOPTIONS *Options );
Pascal/Delphiuses MFstd;
procedure VF_getNonlinfitOptions( var Options: VF_NONLINFITOPTIONS );
DescriptionThe 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.
See alsochapter 13.3

 
MF_Hanning MD_Hanning ME_Hanning
Functiontwo-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/Delphiuses MFstd;
procedure MF_Hanning( MA:fMatrix; ht, len:UInt );
DescriptionMAi,j = 0.25 * (1 - cos( 2 p i / (ht-1) )) * (1 - cos( 2 p j / (len-1) ))
See alsoMF_Parzen,   MF_Welch,   MF_spectrum

 
MCF_hermconj MCD_hermconj MCE_hermconj
FunctionHermitian 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/Delphiuses MCFstd;
procedure MCF_hermconj( MTr, MA:cfMatrix; htTr, lenTr:UInt );
DescriptionThe 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.
See alsoMCF_transpose,   MCF_conj,   chapter 5

 
MCF_HmulM MCD_HmulM MCE_HmulM
Functionmultiply 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/Delphiuses MCFstd;
procedure MCF_HmulM( MC, MA, MB:cfMatrix; htA, lenA, lenB:UInt );
DescriptionMC = 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.
See alsoMCF_hermconj,   MCF_mulMH,   MF_TmulM,   chapter 9

 
MF_inv MD_inv ME_inv
MCF_inv MCD_inv MCE_inv
Functionmatrix inversion
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/Delphiuses MFstd;
function MF_inv( MInv, MA:fMatrix; len:UInt ):IntBool;
DescriptionThe 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 valueFALSE (0), if no error occurred, otherwise TRUE (non-zero).
See alsochapter 10

 
MF_LequU MD_LequU ME_LequU
MCF_LequU MCD_LequU MCE_LequU
Functioncopy 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/Delphiuses MFstd;
procedure MF_LequU( MA:fMatrix; len:UInt );
DescriptionMAi,j = MAj,i,  i > j
See alsoMF_UequL,   chapter 3

 
MF_lincomb MD_lincomb ME_lincomb
MCF_lincomb MCD_lincomb MCE_lincomb
Functionlinear 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/Delphiuses MFstd;
procedure MF_lincomb( MC, MA, MB:fMatrix; ht, len:UInt; CA, CB:Single );
DescriptionMC = CA * MA + CB * MB
See alsoMF_Rows_lincomb,   chapter 9

 
VF_linfit VD_linfit VE_linfit
VF_linfitwW VD_linfitwW VE_linfitwW
FunctionData-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/Delphiuses 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 );

DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
X, Y, InvVarvectors of size sizex, holding the input data
funcsuser-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.

See alsoMF_linfit,   VF_nonlinfit,   chapter 13,  FITDEMO*.*

 
MF_linfit MD_linfit ME_linfit
MF_linfitwW MD_linfitwW ME_linfitwW
FunctionData-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/Delphiuses 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 );

DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
X, Yvectors of size lenZ and htZ, respectively, spanning the x-y coordinate system of the matrix MZ
MZ, MInvVarmatrices of dimensions [htZ, lenZ], holding the input data and, in the weighted variant, the inverse of their variances
funcsuser-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.

See alsoVF_linfit,   MF_nonlinfit,   chapter 13,  FITDEMO*.*

 
MF_LUdecompose MD_LUdecompose ME_LUdecompose
MCF_LUdecompose MCD_LUdecompose MCE_LUdecompose
FunctionLU decomposition
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/Delphiuses MFstd;
function MF_LUdecompose( MLU:fMatrix; Ind:uVector; MA:fMatrix; len:UInt ):Integer;
DescriptionMA 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 handlingIn 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
See alsochapter 10

 
MF_LUdet MD_LUdet ME_LUdet
MCF_LUdet MCD_LUdet MCE_LUdet
Functiondeterminant 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/Delphiuses MFstd;
function MF_LUdet( MLU:fMatrix; len:UInt; permut:Integer ): Single;
DescriptionMF_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
Return valuedeterminant
See alsoMF_det,   chapter 10

 
MF_LUDgetEdit MD_LUDgetEdit ME_LUDgetEdit
MCF_LUDgetEdit MCD_LUDgetEdit MCE_LUDgetEdit
Functionretrieve 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/Delphiuses MFstd;
function MF_LUDgetEdit: Single;
Descriptionretrieve the current pivot-editing threshold for MF_LUdecompose,   MF_inv, and MF_solve. It can be modified using MF_LUDsetEdit.
See alsochapter 10

 
MF_LUDresult MD_LUDresult ME_LUDresult
MCF_LUDresult MCD_LUDresult MCE_LUDresult
Functioncheck 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/Delphiuses MFstd;
function MF_LUDresult: IntBool;
DescriptionAfter 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.
Return valuesee above
See alsochapter 10

 
MF_LUDsetEdit MD_LUDsetEdit ME_LUDsetEdit
MCF_LUDsetEdit MCD_LUDsetEdit MCE_LUDsetEdit
Functionset 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/Delphiuses MFstd;
procedure MF_LUDsetEdit( Thresh:Single );
Descriptionset the pivot-editing threshold for MF_LUdecompose,   MF_inv, and MF_solve. To read the current threshold, use MF_LUDgetEdit
See alsochapter 10

 
MF_LUimprove MD_LUimprove ME_LUimprove
MCF_LUimprove MCD_LUimprove MCE_LUimprove
Functioniterative 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/Delphiuses MFstd;
procedure MF_LUimprove( X, B:fVector; MA, MLU:fMatrix; Ind:uVector; len:UInt );
DescriptionEspecially 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.
See alsochapter 10

 
MF_LUinv MD_LUinv ME_LUinv
MCF_LUinv MCD_LUinv MCE_LUinv
Functioninvert 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/Delphiuses MFstd;
procedure MF_LUinv( MInv, MLU:fMatrix; Ind:uVector; len:UInt );
DescriptionMF_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
See alsochapter 10

 
MF_LUsolve MD_LUsolve ME_LUsolve
MCF_LUsolve MCD_LUsolve MCE_LUsolve
Functionsolve 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/Delphiuses MFstd;
procedure MF_LUsolve( X:fVector; MLU:fMatrix; B:fVector; Ind:uVector; len:UInt );
DescriptionThe 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.
See alsochapter 10

 
MF_matrix MD_matrix ME_matrix
MCF_matrix MCD_matrix MCE_matrix
FunctionMemory allocation for a matrix
Syntax C/C++#include <MFstd.h>
fMatrix F_matrix( unsigned ht, unsigned len );
Pascal/Delphiuses MFstd;
function MF_matrix( ht, len:UInt ): fMatrix;
DescriptionBased 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 handlingIf 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 valueC/C++: Pointer to the array of row pointers
Pascal/Delphi: Pointer to the allocated memory
See alsoMF_matrix0,   VF_vector,   chapter 2

 
MF_matrix0 MD_matrix0 ME_matrix0
MCF_matrix0 MCD_matrix0 MCE_matrix0
Functionallocate memory for a matrix and initialize all elements with 0
Syntax C/C++#include <MFstd.h>
fMatrix F_matrix0( unsigned ht, unsigned len );
Pascal/Delphiuses MFstd;
function MF_matrix0( ht, len:UInt ): fMatrix;
DescriptionThe 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 handlingIf 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 valueC/C++: Pointer to the array of row pointers
Pascal/Delphi: Pointer to the allocated memory
See alsoMF_matrix,   VF_vector0,   chapter 2

 
MF_MatrixTo2DArray MD_MatrixTo2DArray ME_MatrixTo2DArray
MCF_MatrixTo2DArray MCD_MatrixTo2DArray MCE_MatrixTo2DArray
Functionconvert OptiVec matrix into 2D-array of Delphi 4 or higher
Syntax C/C++N.A.
Pascal/Delphiuses VecLib, MFstd;
type fArray = array of Single;
type f2DArray = array of fArray;
procedure MF_MatrixTo2DArray( DelphiArr:f2DArray; MF:fMatrix; ht,len:UInt);
DescriptionThis 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.
See alsoMF_2DArrayToMatrix,   chapter 1.4

 
MF_mulC MD_mulC ME_mulC
MCF_mulC MCD_mulC MCE_mulC
MCF_mulReC MCD_mulReC MCE_mulReC
Functionmultiply 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/Delphiuses MFstd;
procedure MF_mulC( MB, MA:fMatrix; ht, len:UInt; C:Single );
DescriptionMBij = MAij + C
See alsoMF_mulV,   MF_mulM,   chapter 9

 
VF_mulM VD_mulM VE_mulM
Functionmultiply 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/Delphiuses MFstd;
procedure VF_mulM( Y, X:fVector; MA:fMatrix; htA, lenA:UInt );
DescriptionY = X * MA;
the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = htA, sizY = lenA.
See alsoMF_mulV,   MF_mulM,   chapter 9

 
MF_mulM MD_mulM ME_mulM
MCF_mulM MCD_mulM MCE_mulM
Functionmatrix 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/Delphiuses MFstd;
procedure MF_mulM( MC, MA, MB:fMatrix; htA, lenA, lenB:UInt );
DescriptionMC = MA * MB
htA, lenA, and lenB must be specified; the other dimensions are implicitly given as: htB = lenA, lenC = lenB, htC = htA.
See alsoMF_mulMT,   MF_TmulM,   VF_mulM,   chapter 9

 
MFdia_mulM MDdia_mulM MEdia_mulM
MCFdia_mulM MCDdia_mulM MCEdia_mulM
Functionmultiplication 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/Delphiuses MFstd;
procedure MFdia_mulM( MC:fMatrix; MADia: fVector; MB:fMatrix; lenA, lenB:UInt );
DescriptionMC = 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.
See alsoMFdia_mulMT,   chapter 9

 
MF_mulMdia MD_mulMdia ME_mulMdia
MCF_mulMdia MCD_mulMdia MCE_mulMdia
Functionmultiply 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/Delphiuses MFstd;
procedure MF_mulMdia( MC, MA:fMatrix; MBDia:fVector; htA, lenA:UInt );
DescriptionMC = MA * MBDia.
htA and lenA must be specified; sizB = lenA.
See alsoMFdia_mulM,   MF_TmulMdia,   chapter 9

 
MCF_mulMH MCD_mulMH MCE_mulMH
Functionmultiply 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/Delphiuses MCFstd;
procedure MCF_mulMH( MC, MA, MB:cfMatrix; htA, lenA, htB:UInt );
DescriptionMC = MA * MBT *.
htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = lenA, lenC = htB, htC = htA.
See alsoMCF_hermconj,   MF_mulMT,   MCF_HmulM,   chapter 9

 
MF_mulMT MD_mulMT ME_mulMT
MCF_mulMT MCD_mulMT MCE_mulMT
Functionmultiply 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/Delphiuses MFstd;
procedure MF_mulMT( MC, MA, MB:fMatrix; htA, lenA, htB:UInt );
DescriptionMC = MA * MBT.
htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = lenA, lenC = htB, htC = htA.
See alsoMF_mulM,   MF_TmulM,   VF_mulMT,   chapter 9

 
MFdia_mulMT MDdia_mulMT MEdia_mulMT
MCFdia_mulMT MCDdia_mulMT MCEdia_mulMT
Functionmultiply 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/Delphiuses MFstd;
procedure MFdia_mulMT( MC:fMatrix; MADia: fVector; MB:fMatrix; htB, lenB:UInt );
DescriptionMC = MADia * MBT
htB and lenB must be specified; sizA equals lenB.
See alsoMFdia_mulM,   chapter 9

 
VF_mulMT VD_mulMT VE_mulMT
Functionmultiply 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/Delphiuses MFstd;
procedure VF_mulMT( Y, X:fVector; MA:fMatrix; htA, lenA:UInt );
DescriptionY = 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.
See alsoVF_mulM,   MF_mulV,   chapter 9

 
VF_multiLinfit VD_multiLinfit VE_multiLinfit
VF_multiLinfitwW VD_multiLinfitwW VE_multiLinfitwW
Functionfit 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/Delphiuses 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 );

DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
ListOfExperimentsinput data, see chap. 13.4
nexperimentsnumber of data sets in ListOfExperiments
funcsuser-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.

See alsoMF_linfit,   VF_nonlinfit,   chapter 13,  FITDEMO*.*

 
MF_multiLinfit MD_multiLinfit ME_multiLinfit
MF_multiLinfitwW MD_multiLinfitwW ME_multiLinfitwW
Functionfit 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/Delphiuses 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 );
DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
ListOfExperimentsinput data, see chap. 13.4
nexperimentsnumber of data sets in ListOfExperiments
funcsuser-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.

See alsoMF_linfit,   MF_nonlinfit,   MF_multiNonlinfit,   chapter 13,  FITDEMO*.*

 
VF_multiNonlinfit VD_multiNonlinfit VE_multiNonlinfit
VF_multiNonlinfitwW VD_multiNonlinfitwW VE_multiNonlinfitwW
Functionfit 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/Delphiuses 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;

DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
ListOfExperimentsinput data, see chap. 13.4
nexperimentsnumber of data sets in ListOfExperiments
modelfuncuser-defined model function
derivativesuser-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 restrictionsIn 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 handlingIf 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 valuein case of success: goodness-of-fit parameter c2 (chi-square);
in case of failure: -1
See alsoVF_setNonlinfitOptions,   MF_multiNonlinfit,   VF_linfit,   chapter 13,  FITDEMO*.*

 
VF_multiNonlinfit_... VD_multiNonlinfit_... VE_multiNonlinfit_...
VF_multiNonlinfitwW_... VD_multiNonlinfitwW_... VE_multiNonlinfitwW_...
..._autoDeriv
..._getChi2
..._getChi2Detail
..._getBestValues
..._getTestRun
..._getTestPar
..._getTestDir
..._stop
Functionhelper functions for VF_multiNonlinfit and VF_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/Delphiuses 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)
DescriptionVF_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.

See alsochapter 13

 
MF_multiNonlinfit MD_multiNonlinfit ME_multiNonlinfit
MF_multiNonlinfitwW MD_multiNonlinfitwW ME_multiNonlinfitwW
Functionfit 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/Delphiuses 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;

DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
ListOfExperimentsinput data, see chap. 13.4
nexperimentsnumber of data sets in ListOfExperiments
modelfuncuser-defined model function
derivativesuser-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 restrictionsIn 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 handlingIf 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 valuein case of success: goodness-of-fit parameter c2 (chi-square);
in case of failure: -1
See alsoVF_setNonlinfitOptions,   VF_multiNonlinfit,   MF_linfit,   chapter 13,  FITDEMO*.*

 
MF_multiNonlinfit_... MD_multiNonlinfit_... ME_multiNonlinfit_...
MF_multiNonlinfitwW_... MD_multiNonlinfitwW_... ME_multiNonlinfitwW_...
..._autoDeriv
..._getChi2
..._getChi2Detail
..._getBestValues
..._getTestRun
..._getTestPar
..._getTestDir
..._stop
Functionhelper functions for MF_multiNonlinfit and MF_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/Delphiuses 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)
DescriptionMF_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.

See alsochapter 13

 
MF_mulV MD_mulV ME_mulV
MCF_mulV MCD_mulV MCE_mulV
Functionmultiply 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/Delphiuses MFstd;
procedure MF_mulV( Y:fVector; MA:fMatrix; X:fVector; htA, lenA:UInt );
DescriptionY = MA * X
the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = lenA, sizY = htA.
See alsoMF_TmulV,   VF_mulM,   chapter 9

 
MF_neg MD_neg ME_neg
MCF_neg MCD_neg MCE_neg
Functionnegation
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/Delphiuses MFstd;
procedure MF_neg( MB, MA:fMatrix; ht, len:UInt );
DescriptionMBi,j = -MAi,j
See alsoMCF_conj,   chapter 3

 
M_nfree
Functionde-allocate a certain number of matrices (C/C++ only)
Syntax C/C++#include <MFstd.h>
void M_nfree( unsigned numfree, ... );
Pascal/DelphiThis function does not exist
DescriptionThe 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 );
See alsoM_free,  V_freeAll,  chapter 2

 
VF_nonlinfit VD_nonlinfit VE_nonlinfit
VF_nonlinfitwW VD_nonlinfitwW VE_nonlinfitwW
Functionfit y=f(x) data to a model-function which may be nonlinear in its parameters
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));

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) );

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/Delphiuses 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;

DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
X, Y, InvVarvectors of size sizex, holding the input data
modelfuncuser-defined model function
derivativesuser-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 restrictionsIn 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 handlingIf 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 valuein case of success: goodness-of-fit parameter c2 (chi-square);
in case of failure: -1
See alsoVF_setNonlinfitOptions,   MF_nonlinfit,   VF_multiNonlinfit,   VF_linfit,   chapter 13,  FITDEMO*.*

 
VF_nonlinfit_... VD_nonlinfit_... VE_nonlinfit_...
VF_nonlinfitwW_... VD_nonlinfitwW_... VE_nonlinfitwW_...
..._autoDeriv
..._getChi2
..._getBestValues
..._getTestRun
..._getTestPar
..._getTestDir
..._stop
Functionhelper functions for VF_nonlinfit and VF_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/Delphiuses 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)
DescriptionVF_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.

See alsochapter 13

 
MF_nonlinfit MD_nonlinfit ME_nonlinfit
MF_nonlinfitwW MD_nonlinfitwW ME_nonlinfitwW
Functionfit 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/Delphiuses 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;

DescriptionThe 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:
Avector of size npars; returns the coefficients
Covarmatrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatusvector of size npars; decides which parameters are treated as free or as fixed
nparstotal number of parameters
X, Yvectors of size lenZ and htZ, respectively, spanning the x-y coordinate system of the matrix MZ
MZ, MInvVarmatrices of dimensions [htZ, lenZ], holding the input data and, in the weighted variant, the inverse of their variances
modelfuncuser-defined model function
derivativesuser-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 restrictionsIn 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 handlingIf 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 valuein case of success: goodness-of-fit parameter c2 (chi-square);
in case of failure: -1
See alsoVF_setNonlinfitOptions,   VF_nonlinfit,   MF_multiNonlinfit,   MF_linfit,   chapter 13,  FITDEMO*.*

 
MF_nonlinfit_... MD_nonlinfit_... ME_nonlinfit_...
MF_nonlinfitwW_... MD_nonlinfitwW_... ME_nonlinfitwW_...
..._autoDeriv
..._getChi2
..._getBestValues
..._getTestRun
..._getTestPar
..._getTestDir
..._stop
Functionhelper functions for MF_nonlinfit and MF_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/Delphiuses 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)
DescriptionMF_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.

See alsochapter 13

 
MF_outerprod MD_outerprod ME_outerprod
MCF_outerprod MCD_outerprod MCE_outerprod
Functionformation 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/Delphiuses MFstd;
procedure MF_outerprod( MA:fMatrix; X, Y:fVector; ht, len:UInt );
DescriptionMAi,j = Xi * Yj
See alsoVF_mulM,   chapter 3

 
MF_Parzen MD_Parzen ME_Parzen
Functiontwo-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/Delphiuses MFstd;
procedure MF_Parzen( MA:fMatrix; ht, len:UInt );
DescriptionMAi,j = (1 - |(i - 0.5*(ht - 1)) / 0.5*(ht + 1)|) * (1 - |(j - 0.5*(len - 1)) / 0.5*(len + 1)|)
See alsoMF_Hanning,   MF_Welch,   MF_spectrum,   chapter 3

 
MF_Pelement MD_Pelement ME_Pelement
MCF_Pelement MCD_Pelement MCE_Pelement
Functionget 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/Delphiuses MFstd;
function MF_Pelement( MA:fMatrix; ht, len, m, n:UInt ): PSingle;
DescriptionA 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/DelphiMF_Pelement( MA, ht, len, m, n )^ := 3.5;

Read-only access to matrix elements is provided by the related function, MF_element

Return valuepointer to the matrix element MAm,n
See alsoMF_element,   chapter 2

 
VF_polyfit VD_polyfit VE_polyfit
VF_polyfitwW VD_polyfitwW VE_polyfitwW
Functionfitting 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/Delphiuses 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 );
DescriptionThe 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:
Avector of size deg+1; returns the coefficients
Covarmatrix of dimensions [deg+1, deg+1]; returns the covariances of the coefficients
degthe degree of the fitting polynomial
X, Y, InvVarvectors of size sizex, holding the input data

See alsoVF_linregress,   VF_linfit,   VF_chi2,   chapter 13

 
MF_print MD_print ME_print
MCF_print MCD_print MCE_print
Functionprint 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/Delphiuses MFstd;
procedure MF_print( MA:fMatrix; ht, len:UInt );
DescriptionThe 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.

See alsoVF_print,   MF_cprint,   MF_fprint,   chapter 14

 
MF_random MD_random ME_random
MCF_random MCD_random MCE_random
Functionfill 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/Delphiuses MFstd;
  function MF_random( MA:fMatrix; ht, len:UInt; seed:LongInt; MinVal, MaxVal:Single ): LongInt;
DescriptionThe 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.

Error handlingnone
Return valuelast 32-bit random number generated; this may be used as a new seed value for future calls.
See alsoVF_random,   chapter 3

 
MF_read MD_read ME_read
MCF_read MCD_read MCE_read
Functionread 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/Delphiuses 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 );
DescriptionThe 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 handlingC/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.
See alsoMF_write,   VF_nread,   MF_store,   MF_recall,   chapter 14

 
MF_recall MD_recall ME_recall
MCF_recall MCD_recall MCE_recall
FunctionRead 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/Delphiuses MFstd;
procedure MF_recall( MA:fMatrix; ht, len:UInt; var Stream:FILE );
DescriptionThe 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 );.

See alsoMF_store,   chapter 14

 
MF_Row_addC MD_Row_addC ME_Row_addC
MCF_Row_addC MCD_Row_addC MCE_Row_addC
Functionadd 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/Delphiuses MFstd;
procedure MF_Row_addC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
DescriptionMAiRow,i += C,  i=0,...,len-1
See alsoMF_Col_addC,   MF_Dia_addC,   chapter 6

 
MF_Row_addV MD_Row_addV ME_Row_addV
MCF_Row_addV MCD_Row_addV MCE_Row_addV
Functionelement-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/Delphiuses MFstd;
procedure MF_Row_addV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
DescriptionMAiRow,i += Xi,  i=0,...,len-1
See alsoMF_Col_addV,   MF_Dia_addV,   chapter 6

 
MF_Row_delete MD_Row_delete ME_Row_delete
MCF_Row_delete MCD_Row_delete MCE_Row_delete
Functiondelete 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/Delphiuses MFstd;
procedure MF_Row_delete( MB, MA:fMatrix; htA, lenA, iRow:UInt );
DescriptionMBi,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
See alsoMF_Row_insert,   MF_Col_delete,   chapter 5

 
MF_Row_divC MD_Row_divC ME_Row_divC
MCF_Row_divC MCD_Row_divC MCE_Row_divC
Functiondivide 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/Delphiuses MFstd;
procedure MF_Row_divC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
DescriptionMAiRow,i /= C,  i=0,...,len-1
See alsoMF_Col_divC,   MF_Dia_divC,   chapter 6

 
MF_Row_divrC MD_Row_divrC ME_Row_divrC
MCF_Row_divrC MCD_Row_divrC MCE_Row_divrC
Functionreverse 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/Delphiuses MFstd;
procedure MF_Row_divrC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
DescriptionMAiRow,i = C / MAiRow,i,  i=0,...,len-1
See alsoMF_Col_divrC,   MF_Dia_divrC,   chapter 6

 
MF_Row_divrV MD_Row_divrV ME_Row_divrV
MCF_Row_divrV MCD_Row_divrV MCE_Row_divrV
Functionelement-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/Delphiuses MFstd;
procedure MF_Row_divrV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
DescriptionMAiRow,i = Xi / MAiRow,i,  i=0,...,len-1
See alsoMF_Col_divrV,   MF_Dia_divrV,   chapter 6

 
MF_Row_divV MD_Row_divV ME_Row_divV
MCF_Row_divV MCD_Row_divV MCE_Row_divV
Functionelement-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/Delphiuses MFstd;
procedure MF_Row_divV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
DescriptionMAiRow,i /= Xi,  i=0,...,len-1
See alsoMF_Col_divV,   MF_Dia_divV,   chapter 6

 
MF_Row_equ0 MD_Row_equ0 ME_Row_equ0
MCF_Row_equ0 MCD_Row_equ0 MCE_Row_equ0
Functioninitialize 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/Delphiuses MFstd;
procedure MF_Row_equ0( MA:fMatrix; ht, len, iRow:UInt );
DescriptionMAiRow,i = 0,  i=0,...,len-1
See alsoMF_Col_equ0,   MF_Dia_equ0,   MF_Row_equC,   chapter 3

 
MF_Row_equC MD_Row_equC ME_Row_equC
MCF_Row_equC MCD_Row_equC MCE_Row_equC
Functioninitialize 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/Delphiuses MFstd;
procedure MF_Row_equC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
DescriptionMAiRow,i = C,  i=0,...,len-1
See alsoMF_Col_equC,   MF_Dia_equC,   MF_Row_equ0,   chapter 3

 
MF_Row_equV MD_Row_equV ME_Row_equV
MCF_Row_equV MCD_Row_equV MCE_Row_equV
Functioncopy 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/Delphiuses MFstd;
procedure MF_Row_equV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
DescriptionMAiRow,i = Xi,  i=0,...,len-1
See alsoMF_Col_equV,   MF_Dia_equV,   MF_Row_equC,   chapter 3

 
MF_Row_extract MD_Row_extract ME_Row_extract
MCF_Row_extract MCD_Row_extract MCE_Row_extract
Functioncopy 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/Delphiuses MFstd;
procedure MF_Row_extract( Y:fVector; MA:fMatrix; ht, len, iRow:UInt );
DescriptionXi = MAiRow,i,  i=0,...,len-1
See alsoMF_Row_equV,   MF_Row_insert  chapter 5

 
MF_Row_insert MD_Row_insert ME_Row_insert
MCF_Row_insert MCD_Row_insert MCE_Row_insert
Functionaugment 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/Delphiuses MFstd;
procedure MF_Row_insert( MB, MA:fMatrix; htB, lenB, iRow:UInt; X:fVector );
DescriptionMBi,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
See alsoMF_Row_delete,   chapter 5

 
MF_Row_mulC MD_Row_mulC ME_Row_mulC
MCF_Row_mulC MCD_Row_mulC MCE_Row_mulC
Functionmultiply 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/Delphiuses MFstd;
procedure MF_Row_mulC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
DescriptionMAiRow,i *= C,  i=0,...,len-1
See alsoMF_Col_mulC,   MF_Dia_mulC,   MF_Row_mulV,   chapter 6

 
MF_Row_mulV MD_Row_mulV ME_Row_mulV
MCF_Row_mulV MCD_Row_mulV MCE_Row_mulV
Functionelement-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/Delphiuses MFstd;
procedure MF_Row_mulV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
DescriptionMAiRow,i *= Xi,  i=0,...,len-1
See alsoMF_Col_mulV,   MF_Dia_mulV,   MF_Row_divV,   chapter 6

 
MF_Row_subC MD_Row_subC ME_Row_subC
MCF_Row_subC MCD_Row_subC MCE_Row_subC
Functionsubtract 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/Delphiuses MFstd;
procedure MF_Row_subC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
DescriptionMAiRow,i -= C,  i=0,...,len-1
See alsoMF_Col_subC,   MF_Dia_subC,   MF_Row_subV,   chapter 6

 
MF_Row_subrC MD_Row_subrC ME_Row_subrC
MCF_Row_subrC MCD_Row_subrC MCE_Row_subrC
Functionreverse 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/Delphiuses MFstd;
procedure MF_Row_subrC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
DescriptionMAiRow,i = C - MAiRow,i,  i=0,...,len-1
See alsoMF_Row_subC,   MF_Col_subrC,   MF_Dia_subrC,   MF_Row_subV,   chapter 6

 
MF_Row_subrV MD_Row_subrV ME_Row_subrV
MCF_Row_subrV MCD_Row_subrV MCE_Row_subrV
Functionelement-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/Delphiuses MFstd;
procedure MF_Row_subrV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
DescriptionMAiRow,i = Xi - MAiRow,i,  i=0,...,len-1
See alsoMF_Row_subV,   MF_Col_subrV,   MF_Dia_subrV,   MF_Row_addV,   chapter 6

 
MF_Row_subV MD_Row_subV ME_Row_subV
MCF_Row_subV MCD_Row_subV MCE_Row_subV
Functionelement-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/Delphiuses MFstd;
procedure MF_Row_subV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
DescriptionMAiRow,i -= Xi,  i=0,...,len-1
See alsoMF_Row_subC,   MF_Col_subV,   MF_Dia_subV,   MF_Row_subrV,   chapter 6

 
MF_Rows_absmax MD_Rows_absmax ME_Rows_absmax
MCF_Rows_absmax MCD_Rows_absmax MCE_Rows_absmax
Functionstore 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/Delphiuses MFstd;
procedure MF_Rows_absmax( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionThe maximum absolute value of each row i is stored as the element Yi for i=0,...,ht-1
See alsoMF_Rows_max,   MF_Rows_absmin,   MF_Cols_absmax,   MF_Dia_absmax,   chapter 7

 
MCF_Rows_absmaxReIm MCD_Rows_absmaxReIm MCE_Rows_absmaxReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Rows_absmaxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe maximum absolute values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1
See alsoMCF_Rows_absmax,   MCF_Rows_maxReIm,   MCF_Cols_absmaxReIm,   chapter 7

 
MF_Rows_absmin MD_Rows_absmin ME_Rows_absmin
MCF_Rows_absmin MCD_Rows_absmin MCE_Rows_absmin
Functionstore 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/Delphiuses MFstd;
procedure MF_Rows_absmin( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionThe minimum absolute value of each row i is stored as the element Yi for i=0,...,ht-1
See alsoMF_Rows_min,   MF_Rows_absmax,   MF_Cols_absmin,   MF_Dia_absmin,   chapter 7

 
MCF_Rows_absminReIm MCD_Rows_absminReIm MCE_Rows_absminReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Rows_absminReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe maximum absolute values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1
See alsoMCF_Rows_absmin,   MCF_Rows_minReIm,   MCF_Cols_absminReIm,   chapter 7

 
MF_Rows_add MD_Rows_add ME_Rows_add
MCF_Rows_add MCD_Rows_add MCE_Rows_add
Functionmake 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/Delphiuses MFstd;
procedure MF_Rows_add( MA:fMatrix; ht, len, destRow, sourceRow:UInt );
DescriptionMAdestRow, j += MAsourceRow, j,  i=0,...,len-1
See alsoMF_Rows_sub,   MF_Rows_Cadd,   MF_Rows_lincomb,   chapter 8

 
MCF_Rows_cabsmax MCD_Rows_cabsmax MCE_Rows_cabsmax
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Rows_cabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Rows_absmax,   MCF_Rows_cabsmin,   MCF_Rows_sabsmax,   MCF_Cols_cabsmax,   MCF_Dia_cabsmax,   chapter 7

 
MCF_Rows_cabsmin MCD_Rows_cabsmin MCE_Rows_cabsmin
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Rows_cabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Rows_absmin,   MCF_Rows_cabsmax,   MCF_Rows_sabsmin,   MCF_Cols_cabsmin,   MCF_Dia_cabsmin,   chapter 7

 
MF_Rows_Cadd MD_Rows_Cadd ME_Rows_Cadd
MCF_Rows_Cadd MCD_Rows_Cadd MCE_Rows_Cadd
Functionmake 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/Delphiuses MFstd;
procedure MF_Rows_Cadd( MA:fMatrix; ht, len, destRow, sourceRow:UInt; C:Single );
DescriptionMAdestRow, j += C * MAsourceRow, j,  i=0,...,len-1
See alsoMF_Rows_add,   MF_Rows_lincomb,   chapter 8

 
MF_Rows_exchange MD_Rows_exchange ME_Rows_exchange
MCF_Rows_exchange MCD_Rows_exchange MCE_Rows_exchange
Functionexchange 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/Delphiuses MFstd;
procedure MF_Rows_exchange( MA:fMatrix; ht, len, i1, i2:UInt );
DescriptionThe elements of the rows i1 and i2 are exchanged.
See alsoMF_Cols_exchange,   chapter 8

 
MF_Rows_lincomb MD_Rows_lincomb ME_Rows_lincomb
MCF_Rows_lincomb MCD_Rows_lincomb MCE_Rows_lincomb
Functionlinear 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/Delphiuses MFstd;
procedure MF_Rows_lincomb( MA:fMatrix; ht, len:UInt; destRow:UInt; destC:Single; srceRow:Uint; srceC:Single );
DescriptionMAdestRow, j = destC * MAdestRow, j+ srceC * MAsrceRow, j,  j=0,...,len-1
See alsoMF_Rows_add,   MF_Rows_Cadd,   chapter 8

 
MF_Rows_max MD_Rows_max ME_Rows_max
MCF_Rows_max MCD_Rows_max MCE_Rows_max
Functionstore 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/Delphiuses MFstd;
procedure MF_Rows_max( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionThe maximum value of each row i is stored as the element Yi for i=0,...,ht-1
See alsoMF_Rows_absmax,   MF_Rows_min,   MF_Cols_max,   chapter 7

 
MCF_Rows_maxReIm MCD_Rows_maxReIm MCE_Rows_maxReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Rows_maxReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe maximum values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1
See alsoMCF_Rows_absmax,   MCF_Rows_minReIm,   MCF_Cols_maxReIm,   MCF_Rows_absmaxReIm,   chapter 7

 
MF_Rows_min MD_Rows_min ME_Rows_min
MCF_Rows_min MCD_Rows_min MCE_Rows_min
Functionstore 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/Delphiuses MFstd;
procedure MF_Rows_min( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionThe smallest or most negative element of each row i is stored as the element Yi for i=0,...,ht-1
See alsoMF_Rows_absmin,   MF_Rows_max,   MF_Cols_min,   chapter 7

 
MCF_Rows_minReIm MCD_Rows_minReIm MCE_Rows_minReIm
FunctionSeparate 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/Delphiuses MFstd;
procedure MCF_Rows_minReIm( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionThe minimum values of the real and imaginary parts of each row i are combined into the element Yi for i=0,..,ht-1
See alsoMCF_Rows_absmin,   MCF_Rows_maxReIm,   MCF_Cols_minReIm,   MCF_Rows_absminReIm,   chapter 7

 
MF_Rows_prod MD_Rows_prod ME_Rows_prod
MCF_Rows_prod MCD_Rows_prod MCE_Rows_prod
Functionproducts 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/Delphiuses MFstd;
procedure MF_Rows_prod(Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionYi = prod( MAi,j, j=0,...,len-1),  i=0,...,ht-1
See alsoMF_Rows_runprod,   MF_Rows_sum,   chapter 7

 
MF_Rows_reflect MD_Rows_reflect ME_Rows_reflect
FunctionDerive 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/Delphiuses MFstd;
procedure MF_Rows_reflect( MA:fMatrix; ht, len:UInt );
DescriptionMAi, len-j-1 = MAi, j,  i=0,...,ht-1;  j=0,...,(len-1)/2;
See alsoMF_Rows_rotate,   MF_Cols_reflect,   chapter 7

 
MF_Rows_rotate MD_Rows_rotate ME_Rows_rotate
MCF_Rows_rotate MCD_Rows_rotate MCE_Rows_rotate
Functionrotate 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/Delphiuses MFstd;
procedure MF_Rows_rotate( MA:fMatrix; ht, len:UInt; pos:Integer );
DescriptionMAi,j = MAi, len-pos+j,   j=0,..,pos-1
MAi,j = MAi, j-pos,      j=pos,...,len-1
See alsoMF_Rows_reflect,   MF_Cols_rotate,   chapter 7

 
MF_Rows_runprod MD_Rows_runprod ME_Rows_runprod
MCF_Rows_runprod MCD_Rows_runprod MCE_Rows_runprod
Functionrunning 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/Delphiuses MFstd;
procedure MF_Rows_runprod( MA:fMatrix; ht, len:UInt );
DescriptionFor 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.
See alsoMF_Rows_prod,   MF_Cols_runprod,   chapter 7

 
MF_Rows_runsum MD_Rows_runsum ME_Rows_runsum
MCF_Rows_runsum MCD_Rows_runsum MCE_Rows_runsum
Functionrunning 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/Delphiuses MFstd;
procedure MF_Rows_runsum( MA:fMatrix; ht, len:UInt );
DescriptionFor all rows separately, each element is the sum of itself and all preceding elements.
See alsoMF_Rows_sum,   MF_Cols_runsum,   chapter 7

 
MCF_Rows_sabsmax MCD_Rows_sabsmax MCE_Rows_sabsmax
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Rows_sabsmax( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Rows_absmax,   MCF_Rows_sabsmin,   MCF_Cols_sabsmax,   MCF_Dia_sabsmax,   MCF_Rows_cabsmax,   chapter 7

 
MCF_Rows_sabsmin MCD_Rows_sabsmin MCE_Rows_sabsmin
FunctionFind 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/Delphiuses MCFstd;
procedure MCF_Rows_sabsmin( Y:cfVector; MA:cfMatrix; ht, len:UInt );
DescriptionWithin 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
See alsoMCF_Rows_absmin,   MCF_Rows_cabsmin,   MCF_Rows_sabsmax,   MCF_Cols_sabsmin,   MCF_Dia_sabsmin,   chapter 7

 
MF_Rows_sub MD_Rows_sub ME_Rows_sub
MCF_Rows_sub MCD_Rows_sub MCE_Rows_sub
Functionmake 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/Delphiuses MFstd;
procedure MF_Rows_sub( MA:fMatrix; ht, len, destRow, sourceRow:UInt; );
DescriptionMAdestRow, j -= MAsourceRow, j,  i=0,...,len-1
See alsoMF_Rows_add,   MF_Rows_Cadd,   chapter 8

 
MF_Rows_sum MD_Rows_sum ME_Rows_sum
MCF_Rows_sum MCD_Rows_sum MCE_Rows_sum
Functionsums 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/Delphiuses MFstd;
procedure MF_Rows_sum( Y:fVector; MA:fMatrix; ht, len:UInt );
DescriptionYi = sum( MAi,j, j=0,...,len-1),  i=0,...,ht-1
See alsoMF_Rows_runsum,   MF_Rows_prod,   chapter 7

 
MF_safeSolve MD_safeSolve ME_safeSolve
Functionsolve 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/Delphiuses MFstd;
function MF_safeSolve( X:fVector; MA:fMatrix; B:fVector; len:UInt ):Integer;
DescriptionMF_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.

See alsoMF_solve,   chapter 10

 
M_setDensityBounds
FunctionCalculate 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/Delphiuses Mgraph;
procedure M_setDensityBounds( zmin, zmax: Extended; mincolor, maxcolor: COLORREF );
DescriptionA 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.
See alsoM_setDensityMapBounds,   M_findDensityMapBounds,   chapter 15

 
M_setDensityMapBounds
FunctionSet 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/Delphiuses Mgraph;
procedure M_setDensityMapBounds( xmin, xmax, ymin, ymax, zmin, zmax: Extended; mincolor, maxcolor: COLORREF );
DescriptionSimilarly 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.

See alsoMF_xyzAutoDensityMap,   MF_zAutoDensityMap,   chapter 15

 
VF_setLinfitNeglect VD_setLinfitNeglect VE_setLinfitNeglect
Functiondefine 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/Delphiuses MFstd;
procedure VF_setLinfitNeglect( Thresh:Single );
DescriptionAs 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.
See alsoVF_getLinfitNeglect,   VF_linfit,   chapter 13

 
VF_setNonlinfitOptions VD_setNonlinfitOptions VE_setNonlinfitOptions
Functionset options for the nonlinear fitting routines
Syntax C/C++#include <MFstd.h>
void VF_setNonlinfitOptions( VF_NONLINFITOPTIONS *Options );
Pascal/Delphiuses MFstd;
procedure VF_setNonlinfitOptions( Options: VF_NONLINFITOPTIONS );
DescriptionThe 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/DelphiOpt: 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 );
See alsochapter 13.3

 
MF_setWriteFormat MD_setWriteFormat ME_setWriteFormat
MCF_setWriteFormat MCD_setWriteFormat MCE_setWriteFormat
FunctionDefinition 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/DelphiThis function does not exist.
DescriptionThese 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.

VersionStandard FormatAlternative Examplemax. 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 handlingFormat 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.
See alsoMF_setWriteSeparate,   MF_write,   VF_write,   MF_read,   chapter 14

 
MF_setWriteSeparate MD_setWriteSeparate ME_setWriteSeparate
MCF_setWriteSeparate MCD_setWriteSeparate MCE_setWriteSeparate
Functiondefine 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/Delphiuses MFstd;
procedure MF_setWriteSeparate( SepString:PChar );
DescriptionThese 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 handlingIn 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.
See alsoMF_setWriteFormat,   MF_write,   MF_read,   chapter 14

 
MF_solve MD_solve ME_solve
MCF_solve MCD_solve MCE_solve
Functionsolve 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/Delphiuses MFstd;
function MF_solve( X:fVector; MA:fMatrix; B:fVector; len:UInt ): IntBool;
DescriptionThis 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 valueFALSE (0), if the linear system could by solved; TRUE (1) in the case of a singular system without pivot-editing
See alsoMF_LUdecompose,   MF_inv,   chapter 10

 
MF_solveBySVD MD_solveBySVD ME_solveBySVD
Functionsolve 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/Delphiuses MFstd;
function MF_solveBySVD( X:fVector; MA:fMatrix; B:fVector; htA, lenA:UInt ): IntBool;
DescriptionThe 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 valueusually FALSE (0); only in the very rare case of failure, TRUE (1)
See alsoMF_SVdecompose,   MF_solve,   chapter 10

 
MF_spectrum MD_spectrum ME_spectrum
Functionspatial 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/Delphiuses MFstd;
procedure MF_spectrum( MSpec:fMatrix; htSpec, lenSpec:UInt; MX:fMatrix; htX, lenX:UInt; MWin:fMatrix );
DescriptionThe 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 handlingIf 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.
See alsoMF_FFT,   MF_convolve,   MF_autocorr,   MF_xcorr,   MF_filter,   chapter 12

 
MFsym_sqrt MDsym_sqrt MEsym_sqrt
FunctionSquare 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/Delphiuses MFstd;
function MFsym_sqrt( MB, MA:fMatrix; len:UInt ):IntBool;
DescriptionThe 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 valueFALSE (0), if the matrix square-root could be calculated; otherwise TRUE (1)
See alsoMF_eigenvalues,   chapter 11

 
MF_store MD_store ME_store
MCF_store MCD_store MCE_store
Functionstore 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/Delphiuses MFstd;
procedure MF_store( var Stream:FILE; MA:fMatrix; ht, len:UInt );
DescriptionThe matrix MA of ht*len elements is written to stream in binary format. The stream must be already open for binary write operations.
See alsoMF_recall,   chapter 14

 
MF_subM MD_subM ME_subM
MFs_subM MDs_subM MEs_subM
MCF_subM MCD_subM MCE_subM
Functionelement-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/Delphiuses MFstd;
procedure MF_subM( MC, MA, MB:fMatrix; ht, len:UInt );
procedure MFs_subM( MC, MA, MB:fMatrix; ht, len:UInt; C:Single );
Descriptionnormal version: MCij = MAij - MBij
scaled version: MCij = C * (MAij - MBij)
See alsoMF_subMT,   MF_addM,   chapter 9

 
MF_subMT MD_subMT ME_subMT
MFs_subMT MDs_subMT MEs_subMT
MCF_subMT MCD_subMT MCE_subMT
Functionsubtract 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/Delphiuses MFstd;
procedure MF_subMT( MC, MA, MB:fMatrix; ht, len:UInt );
procedure MFs_subMT( MC, MA, MB:fMatrix; ht, len:UInt; C:Single );
Descriptionnormal version: MCi,j = MAi,j - MBTj,i
scaled version: MCi,j = C * (MAi,j - MBTj,i)
See alsoMF_subM,   MF_addM,   MF_subrMT,   chapter 9

 
MF_subrMT MD_subrMT ME_subrMT
MFs_subrMT MDs_subrMT MEs_subrMT
MCF_subrMT MCD_subrMT MCE_subrMT
Functionreverse 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/Delphiuses MFstd;
procedure MF_subrMT( MC, MA, MB:fMatrix; ht, len:UInt );
procedure MFs_subrMT( MC, MA, MB:fMatrix; ht, len:UInt; C:Single );
Descriptionnormal version: MCi,j = MBTj,i - MAi,j
scaled version: MCi,j = C * (MBTj,i - MAi,j)
See alsoMF_addM,   MF_subMT,   chapter 9

 
MF_submatrix MD_submatrix ME_submatrix
MCF_submatrix MCD_submatrix MCE_submatrix
Functionextract 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/Delphiuses MFstd;
procedure MF_submatrix( MSub:fMatrix; subHt, subLen:UInt; MSrce:fMatrix; srceHt, srceLen:UInt; firstRowInCol, sampInCol, firstColInRow, sampInRow:UInt );
DescriptionMSubi, j = MSrcei*sampInCol+firstRowInCol, j*sampInRow+firstColInRow
See alsoVF_subvector,   MF_Row_extract,   MF_submatrix_equM,   chapter 5

 
MF_submatrix_equM MD_submatrix_equM ME_submatrix_equM
MCF_submatrix_equM MCD_submatrix_equM MCE_submatrix_equM
Functiondistribute 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/Delphiuses MFstd;
procedure MF_submatrix_equM( MDest:fMatrix; destHt, destLen, firstRowInCol, sampInCol, firstColInRow, sampInRow:UInt; MSrce:fMatrix; srceHt, srceLen:UInt );
DescriptionMDesti*sampInCol+firstRowInCol, j*sampInRow+firstColInRow = MSrcei, j
This function does the inverse of MF_submatrix
See alsoVF_subvector,   MF_Row_equV,   MF_submatrix,   chapter 5

 
MF_SVdecompose MD_SVdecompose ME_SVdecompose
FunctionSingular 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/Delphiuses MFstd;
function MF_SVdecompose( MU, MV:fMatrix; W:fVector; MA:fMatrix; htA, lenA:UInt ): IntBool;
DescriptionThe 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:

  1. 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.
  2. 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.
  3. 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.
See alsoMF_SVsolve,   MF_safeSolve,   MF_solveBySVD,   chapter10

 
MF_SVDgetEdit MD_SVDgetEdit ME_SVDgetEdit
Functionretrieve 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/Delphiuses MFstd;
function MF_SVDgetEdit: Single;
DescriptionThis function returns the current Singular Value editing threshold. The SV editing threshold may be modified by MF_SVDsetEdit.
Return valuecurrent SV editing threshold
See alsoMF_SVdecompose,   MF_SVsolve,   chapter 10

 
MF_SVDsetEdit MD_SVDsetEdit ME_SVDsetEdit
Functionset 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/Delphiuses MFstd;
procedure MF_SVDsetEdit( Thresh:Single );
DescriptionAs 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.
See alsoMF_SVdecompose,   MF_SVsolve,   chapter 10

 
MF_SVsolve MD_SVsolve ME_SVsolve
Functionsolve 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/Delphiuses MFstd;
procedure MF_SVsolve( X:fVector; MU, MV:fMatrix; W, B:fVector; htA, lenA:UInt );
DescriptionMF_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;

See alsoMF_SVdecompose,   MF_solveBySVD,   chapter 10

 
MF_TmulM MD_TmulM ME_TmulM
MCF_TmulM MCD_TmulM MCE_TmulM
Functionmultiply 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/Delphiuses MFstd;
procedure MF_TmulM( MC, MA, MB:fMatrix; htA, lenA, lenB:UInt );
DescriptionMC = 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.
See alsoMF_mulM,   MF_mulMT,   chapter 9

 
MF_TmulMdia MD_TmulMdia ME_TmulMdia
MCF_TmulMdia MCD_TmulMdia MCE_TmulMdia
Functionmultiply 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/Delphiuses MFstd;
procedure MF_TmulMdia( MC, MA:fMatrix; MBDia:fVector; htA, lenA:UInt );
DescriptionMC = MAT * MBDia
htA and lenA must be specified. They refer to the original, un-transposed input matrix. Implicitly, sizB = htA.
See alsoMFdia_mulM,   chapter 9

 
MF_TmulMT MD_TmulMT ME_TmulMT
MCF_TmulMT MCD_TmulMT MCE_TmulMT
Functionmultiply 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/Delphiuses MFstd;
procedure MF_TmulMT( MC, MA, MB:fMatrix; htA, lenA, htB:UInt );
DescriptionMC = 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.
See alsoMF_mulM,   MF_TmulM,   MF_mulMT,   chapter 9

 
MF_TmulV MD_TmulV ME_TmulV
MCF_TmulV MCD_TmulV MCE_TmulV
Functionmultiply 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/Delphiuses MFstd;
procedure MF_TmulV( Y:fVector; MA:fMatrix; X:fVector; htA, lenA:UInt );
DescriptionY = 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.
See alsoMF_mulV,   VF_mulM,   chapter 9

 
MF_transpose MD_transpose ME_transpose
MCF_transpose MCD_transpose MCE_transpose
Functiontranspose 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/Delphiuses MFstd;
procedure MF_transpose( MTr, MA:fMatrix; htTr, lenTr:UInt );
DescriptionMTri,j = MAj,i
The dimensions fed into this function, htTr and lenTr, refer to the transposed matrix rather than to the input matrix.
See alsoMCF_hermconj,   MF_mulMT,   chapter 9,   chapter 5

 
MF_Trd_equM MD_Trd_equM ME_Trd_equM
MCF_Trd_equM MCD_Trd_equM MCE_Trd_equM
Functioninitialize 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/Delphiuses MFstd;
procedure MF_Trd_equM( MA, MTrd:fMatrix; len:UInt );
DescriptionRow 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.
See alsoMF_Dia_equV,   MF_Trd_extract,   chapter 2

 
MF_Trd_extract MD_Trd_extract ME_Trd_extract
MCF_Trd_extract MCD_Trd_extract MCE_Trd_extract
Functionextract 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/Delphiuses MFstd;
procedure MF_Trd_extract( MTrd, MA:fMatrix; len:UInt );
DescriptionThe 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.
See alsoMF_Dia_extract,   MF_Trd_equM,   chapter 2

 
MF_UequL MD_UequL ME_UequL
MCF_UequL MCD_UequL MCE_UequL
Functioncopy 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/Delphiuses MFstd;
procedure MF_UequL( MA:fMatrix; len:UInt );
DescriptionMAi,j = MAj,i,  i < j
See alsoMF_LequU,   chapter 3

 
MF_Welch MD_Welch ME_Welch
Functiontwo-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/Delphiuses MFstd;
procedure MF_Welch( MA:fMatrix; ht, len:UInt );
DescriptionMAi,j = (1 - ( (i - 0.5*(ht - 1)) / (0.5*(ht + 1)) )2) * (1 - ( (j - 0.5*(len - 1)) / (0.5*(len + 1)) )2)
See alsoMF_Parzen,   MF_Hanning,   MF_spectrum

 
MF_write MD_write ME_write
MCF_write MCD_write MCE_write
Functionwrite 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/Delphiuses 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 );
DescriptionThe 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.

Error handlingnone
See alsoMF_setWriteFormat,   MF_setWriteSeparate,   MF_read,   MF_store,   MF_print,   chapter 14

 
MF_xcorr MD_xcorr ME_xcorr
Functionspatial 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/Delphiuses MFstd;
procedure MF_xcorr( MC, MA, MB:fMatrix; ht, len:UInt );
DescriptionThe 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 handlingIf 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.
See alsoMF_autocorr,   chapter 12

 
MF_xyzAutoDensityMap MD_xyzAutoDensityMap ME_xyzAutoDensityMap
Functiondraw 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/Delphiuses Mgraph;
procedure MF_xyzAutoDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt; mincolor, maxcolor: COLORREF );
DescriptionA 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.

See alsoMF_zAutoDensityMap,   MF_xyzDataDensityMap,   VF_xyAutoPlot,   chapter 15

 
MF_xyzDataDensityMap MD_xyzDataDensityMap ME_xyzDataDensityMap
Functionplot 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/Delphiuses Mgraph;
procedure MF_xyzDataDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt );
DescriptionThe matrix MZ is plotted against the vectors X and Y into a coordinate system which has to be created by a previous call to MF_setDensityMapBounds or (for automatic scaling) MF_findDensityMapBounds. To perform the plot with automatic range checking and axis scaling, call MF_xyzAutoDensityMap instead.
See alsoMF_zDataDensityMap,   MF_xyzAutoDensityMap,   chapter 15

 
MF_zAutoDensityMap MD_zAutoDensityMap ME_zAutoDensityMap
Functionplot 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/Delphiuses Mgraph;
procedure MF_xyzDataDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt );
DescriptionThis function is similar to MF_xyzAutoDensityMap, but here MZ is plotted against the indices of its dimensions instead of explicit X and Y values.
See alsoMF_xyzAutoDensityMap,   chapter 15

 
MF_zDataDensityMap MD_zDataDensityMap ME_zDataDensityMap
Functionplot 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/Delphiuses Mgraph;
procedure MF_zDataDensityMap( MZ:fMatrix; ht, len: UInt );
DescriptionThis function is similar to MF_xyzDataDensityMap, but here MZ is plotted against the indices of its dimensions instead of explicit X and Y values.
See alsoMF_xyzDataDensityMap,   MF_xyzAutoDensityMap,   chapter 15

 
MF_2DArrayToMatrix MD_2DArrayToMatrix ME_2DArrayToMatrix
MCF_2DArrayToMatrix MCD_2DArrayToMatrix MCE_2DArrayToMatrix
Functionconvert 2D-array of Delphi 4 or higher into OptiVec matrix
Syntax C/C++N.A.
Pascal/Delphiuses MFstd, VecLib;
type fArray = array of Single;
type f2DArray = array of fArray;
procedure MF_2DArrayToMatrix( MF:fMatrix; DelphiArr:f2DArray; ht,len:UInt);
DescriptionThis 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.
See alsoMF_MatrixTo2DArray,   chapter 1.4

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!