| # 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.4 Pascal/Delphi Specifics
2. Management of Dynamically Generated Matrices
3. Initialization of Matrices
4. Data-Type Conversions
5. Transposing, Augmenting, Deleting, Extracting, and Filling Parts of a Matrix
6. Arithmetic Operations Performed on a Single Row, Column, or the Diagonal
7. Operations Performed Along All Rows or All Columns Simultaneously, or the Diagonal
8. Operations Involving Two Rows or Two Colums
9. Whole-Matrix Arithmetics: Addition, Multiplication
10. Linear Algebra
11. Eigenvalues and Eigenvectors, Matrix Square-Root
12. Two-Dimensional Fourier-Transform Methods
13. Data Fitting
13.1 Polynomials
13.2 General Linear Model Functions
13.3 Non-Linear Models
13.4 Fitting Multiple Data Sets
13.5 Helper Functions for Nonlinear Fits
14. Matrix Input and Output
15. Graphical Representation of Matrices
16. Alphabetical Reference for MatrixLib

##

1. Introduction

The MatrixLib part of OptiVec builds upon the principles established in the VectorLib part. You may wish to refer to the introductory chapters of HANDBOOK.HTM, before reading on for MatrixLib.

Back to Table of Contents

### 1.1 Matrix Data Types

As VectorLib defines vector data types, here are the matrix data types, defined in MatrixLib:

fMatrix | matrix of floats
dMatrix | matrix of doubles
eMatrix | matrix of extended (long double)
cfMatrix | matrix of fComplex (complex<float>)
cdMatrix | matrix of dComplex (complex<double>)
ceMatrix | matrix of eComplex (complex<extended>)

The ordering of elements is the same as in the two-dimensional arrays provided by the respective target compilers. This means that the matrices are stored row-wise in MatrixLib versions for C and C++ compilers, but column-wise in the Pascal/Delphi versions.
At present, integer matrices are defined, but no functions are available for them.

While we recommend to exclusively use these dynamically allocated matrix types, static matrices defined, e.g., as
float MX[4][6]; (for C/C++), or
MX: array[0..3][0..5] of Single; (for Pascal/Delphi)
can be used in all MatrixLib functions with the exception of the multiLinfit and multiNonlinfit routines.

Back to Table of Contents

### 1.2 Prefixes of MatrixLib Functions

Each MatrixLib function has a prefix defining the data type on which it acts:

Prefix: | Arguments:
MF_ | fMatrix, float and fVector
MD_ | dMatrix, double and dVector
ME_ | eMatrix, extended (long double) and eVector
MCF_ | cfMatrix, fComplex and cfVector
MCD_ | cdMatrix, dComplex and cdVector
MCE_ | ceMatrix, eComplex and ceVector

In a few cases, the prefix is augmented by a three-letter code denoting special matrix properties:

- MFdia_ means that the function expects a diagonal matrix (i.e., a square matrix which has non-zero elements only on the diagonal); as there is no sense in storing all the zeros, diagonal matrix are actually stored as vectors, holding only the diagonal elements.
- MFsym_ denotes a function which expects the input matrix to be symmetric. At present, only MFsym_eigenvalues and MFsym_sqrt make use of this assumption.
- MFtrd_ means the function is for a tridiagonal matrix (i.e., a square matrix with non-zero elements only on the diagonal plus or minus one column). A tridiagonal matrix has to be entered in the form of a matrix with three rows, representing the three vectors actually containing non-zero data. In other words, the original matrix

  d0 | u0 | 0 | ··· |  |
  l1 | d1 | u1 | 0 | ··· |
  0 | l2 | d2 | u2 | 0 | ···
  |  |  | ··· |  |
  |  |  | lN-2 | dN-2 | uN-2
  |  |  | 0 | lN-1 | dN-1

  is compacted into the form

  u0 | u1 | u2 | ··· | uN-2 | *
  d0 | d1 | d2 | ··· | dN-2 | dN-1
  * | l1 | l2 | ··· | lN-2 | lN-1

  The elements l0 and uN-1, marked with an asterisk, are undefined and never used.

Back to Table of Contents

### 1.3 C/C++ Version Specifics:

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 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 4 or higher:
From version 4 on, Delphi offers dynamic arrays. In the one-dimensional case, they are declared as "array of Single", "array of Double", etc. The VecLib unit includes short-cut definitions for these types as fArray, dArray, etc. By simply type-casting fArrays into fVectors, they can be used with all VectorLib functions.

The situation is more complicated in the two-dimensional case. Dynamic two-dimensional arrays can be created in Delphi by declaring them as "array of fArray", "array of dArray", etc. Short-cut definitions for these types are also given in the VecLib unit, as f2DArray, d2DArray, etc. As a consequence of the described way of defining 2D-Arrays in Delphi, each row of a matrix is stored in a separate vector. This means that the matrix elements do no longer occupy a single, contiguous memory space. Therefore, 2DArrays cannot be used directly with MatrixLib functions. Instead, they have to be copied into matrices by calling MF_2DArrayToMatrix etc., before MatrixLib functions can be used on them. The reverse conversion is available as MF_MatrixTo2DArray.

In the following chapters, a brief summary of all MatrixLib function is given, ordered into groups according to their functionality. At the end of this file, chapter 16 describes all MatrixLibfunctions in alphabetical order.

Back to Table of Contents

##

2. Management of Dynamically Generated Matrices

MF_matrix | allocate memory for a matrix
MF_matrix0 | allocate memory and set all elements 0
M_free | free one matrix (data-type independent)
M_nfree | free n matrices (data-type independent; only C/C++)
V_freeAll | free all existing vectors and matrices

OptiVec's dynamically allocated matrices are aligned on 32-byte boundaries, which allows for optimum cache-line matching for the Pentium processor and its currently available successors and competitors.

C/C++ version only:
OptiVec's dynamically allocated matrices can be addressed just like two-dimensional static arrays of C/C++. If you have, e.g., an fMatrix MX; 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_Pelement | Pointer to a specific matrix element
MF_element | value 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_equ0 | set all elements to 0
MF_equ1 | identity matrix: set all diagonal elements to 1.0, all others to 0
MF_equm1 | negative identity matrix: set all diagonal elements to -1.0, all others to 0
MF_random | fill with random numbers
MF_outerprod | matrix formed by the "outer product" of two vectors
MF_Row_equ0 | set all elements of one specific row to 0
MF_Col_equ0 | set all elements of one specific column to 0
MF_Dia_equ0 | set all diagonal elements to 0
MF_Row_equC | set all elements of one specific row to the constant C
MF_Col_equC | set all elements of one specific column to the constant C
MF_Dia_equC | set all diagonal elements to the constant C
MF_Row_equV | copy a vector into one specific row
MF_Col_equV | copy a vector into one specific column
MF_Dia_equV | copy a vector into the diagonal
MF_Trd_equM | copy a compacted tridiagonal matrix into a general matrix
MF_equM | make one matrix the copy of another
MF_neg | make one matrix the negative of another
MCF_conj | make one matrix the complex conjugate of another
MCF_hermconj | make one matrix the Hermitian conjugate of another: MB = MAT*
MF_UequL | copy lower-diagonal elements into upper-diagonal by index-reflection, so as to get a symmetric matrix
MF_LequU | copy upper-diagonal elements into lower-diagonal

Two-dimensional windows for spectral analysis are provided by:

MF_Hanning | Hanning window
MF_Parzen | Parzen window
MF_Welch | Welch 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_FtoD | fMatrix to dMatrix
M_EtoD | eMatrix to dMatrix (with overflow protection)
M_CDtoCF | cdMatrix to cfMatrix (with overflow protection)
M_DtoE | dMatrix to eMatrix

Back to Table of Contents

##

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

MF_transpose | transpose a matrix: MB = MAT
MCF_hermconj | Hermitian conjugate: MB = MAT*
MF_equMblock | extract a block, i.e. a submatrix for which the sampling interval both along rows and along columns is 1
MF_equMblockT | extract the transpose of a block
MF_submatrix | extract a submatrix with sampling intervals along rows and/or columns possibly different from 1
MF_block_equM | copy a matrix back into a block of another (normally larger) matrix
MF_block_equMT | copy the transpose of a matrix into a block of another (normally larger) matrix
MF_submatrix_equM | copy a submatrix back into another (normally larger) matrix
MF_Row_extract | extract a single row and copy it into a vector
MF_Col_extract | extract a single column and copy it into a vector
MF_Dia_extract | extract the diagonal and copy it into a vector
MF_Trd_extract | extract a tridiagonal matrix from a general matrix
MF_Row_insert | augment a matrix by insertion of one row
MF_Col_insert | augment a matrix by insertion of one column
MF_Row_delete | delete one row of a matrix
MF_Col_delete | delete 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_addC | add a constant to all elements of a specific row
MF_Col_addC | add a constant to all elements of a specific column
MF_Dia_addC | add a constant to all diagonal elements
MF_Row_addV | add corresponding vector elements to all elements of a specific row
MF_Col_addV | add corresponding vector elements to all elements of a specific column
MF_Dia_addV | add corresponding vector elements to the diagonal elements

A few examples should suffice for the other functions of this family:

MF_Row_subC | subtract a constant from all elements of a specific row
MF_Col_subrC | reverse substraction: difference between column elements and a constant
MF_Dia_mulV | multiply the diagonal elements with corresponding vector elements
MF_Row_divV | divide all elements of a specific row by corresponding vector elements
MF_Col_divrC | reverse division: division of a constant by the individual column elements

Back to Table of Contents

##

7. Operations Performed Along All Rows or All Columns Simultaneously, or Along the Diagonal of a Square Matrix

MF_Rows_max | store the maxima of all rows in a column vector
MF_Cols_max | store the maxima of all colums in a row vector
MF_Dia_max | return the maximum of the diagonal as a scalar
MF_Rows_absmax | store the absolute maxima of all rows in a column vector
MF_Cols_absmax | store the absolute maxima of all colums in a row vector
MF_Dia_absmax | return the absolute maximum of the diagonal as a scalar
MF_Rows_sum | sum, taken along rows and stored in a column vector
MF_Cols_sum | sum, taken along colums and stored in a row vector
MF_Dia_sum | sum of the diagonal elements
MF_Rows_prod | product, taken along rows and stored in a column vector
MF_Cols_prod | product, taken along colums and stored in a row vector
MF_Dia_prod | product of the diagonal elements
MF_Rows_runsum | running sum along rows
MF_Cols_runsum | running sum along columns
MF_Rows_runprod | running product along rows
MF_Cols_runprod | running product along columns
MF_Rows_rotate | rotate all rows by a specified number of positions
MF_Cols_rotate | rotate all columns by a specified number of positions
MF_Rows_reflect | set the upper halves of all rows equal to their reversed lower halves
MF_Cols_reflect | set 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_absmax | store the maxima of the absolute values of all rows in a (real-valued) column vector
MCF_Cols_absmax | store the maxima of the absolute values of all colums in a (real-valued) row vector
MCF_Dia_absmax | return the maximum of the absolute values of the diagonal elements as a (real) scalar
MCF_Rows_absmaxReIm | find the maximum absolute values of all real and of all imaginary parts separately along the rows of a matrix; merge the maxima into complex numbers, and store them in a column vector
MCF_Cols_absmaxReIm | find the maximum absolute values of all real and of all imaginary parts separately along the columns of a matrix; merge the maxima into complex numbers, and store them in a row vector
MCF_Dia_absmaxReIm | find the maximum absolute values of all real and of all imaginary parts separately along the diagonal of a square matrix; merge these two maxima into one complex number and return it as a scalar
MCF_Rows_cabsmax | find the complex numbers of largest magnitude along rows and store these row maxima in a (complex) column vector
MCF_Cols_cabsmax | find the complex numbers of largest magnitude along columns and store these column maxima in a (complex) row vector
MCF_Dia_cabsmax | find the complex number of largest magnitude along the diagonal of a square matrix and return it as a (complex) scalar
MCF_Rows_maxReIm | find the maxima of all real and of all imaginary parts separately along the rows of a matrix; merge the maxima into complex numbers, and store them in a column vector
MCF_Cols_maxReIm | find the maxima of all real and of all imaginary parts separately along the columns of a matrix; merge the maxima into complex numbers, and store them in a row vector
MCF_Dia_maxReIm | find the maximum of all real and of all imaginary parts separately along the diagonal of a square matrix; merge these two maxima into one complex number and return it as a scalar
MCF_Rows_sabsmax | find the complex numbers of largest sum |Re|+|Im| along rows and store these row maxima in a (complex) column vector
MCF_Cols_sabsmax | find the complex numbers of largest sum |Re|+|Im| along columns and store these column maxima in a (complex) row vector
MCF_Dia_sabsmax | find the complex number of largest sum |Re|+|Im| along the diagonal of a square matrix and return it as a (complex) scalar

Back to Table of Contents

##

8. Operations Involving Two Rows or Two Colums

MF_Rows_exchange | exchange two rows
MF_Cols_exchange | exchange two columns
MF_Rows_add | add one row to another (destination += source)
MF_Cols_add | add one column to another
MF_Rows_sub | subtract one row from another (destination -= source)
MF_Cols_sub | subtract one column from another
MF_Rows_Cadd | add scaled row to another (destination += C * source)
MF_Cols_Cadd | add scaled column to another
MF_Rows_lincomb | linear combination of two rows
MF_Cols_lincomb | linear combination of two columns

Back to Table of Contents

##

9. Whole-Matrix Arithmetics: Addition, Multiplication

a) Element-wise operations

MF_addM | add two matrices
MF_addMT | add one matrix and the transpose of another matrix MC = MA + MBT
MF_subM | subtract one matrix from another
MF_subMT | subtract a transposed matrix MC = MA - MBT
MF_subrMT | subtract a matrix from another, transposed, matrix MC = MBT - MA
MF_mulC | multiply all matrix elements by a constant
MCF_mulReC | multiply all elements of a complex matrix by a real number
MF_divC | divide all matrix elements by a constant
MCF_divReC | divide all elements of a complex matrix by a real number
MFs_addM | scaled addition of two matrices: MC = c * (MA + MB)
MFs_addMT | scaled addition of one matrix and the transpose of another: MC = c * (MA + MBT)
MFs_subM | scaled subtraction of two matrices: MC = c * (MA - MB)
MFs_subMT | scaled subtraction of one matrix and the transpose of another: MC = c * (MA - MBT)
MFs_subrMT | scaled reverse subtraction of one matrix and the transpose of another: MC = c * (MBT - MA)
MF_lincomb | linear combination: MC = ca * MA + cb * MB

b) Matrix multiplication:

MF_mulV | multiply a matrix by a column vector: Y = MA * X
MF_TmulV | multiply the transpose of a matrix by a column vector: Y = MAT * X
VF_mulM | multiply a row vector by a matrix: Y = X * MA
VF_mulMT | multiply a row vector by the transpose of a matrix: Y = X * MAT
MF_mulM | multiply two matrices: MC = MA * MB
MF_mulMT | multiply one matrix by the transpose of another matrix: MC = MA * MBT
MF_TmulM | multiply the transpose of a matrix by another matrix: MC = MAT * MB
MF_TmulMT | multiply the transpose of one matrix by the transpose of another matrix: MC = MAT * MBT
MCF_mulMJ | multiply one matrix by the hermitian conjugate of another matrix: MC = MA * MBT *
MCF_HmulM | multiply the hermitian conjugate of a matrix by another matrix: MC = MAT * * MB

c) Multiplications of general matrices by diagonal matrices or vice versa
The diagonal matrix is passed to the respective function as a vector.

MF_mulMdia | multiply a general matrix by a diagonal matrix: MC = MA * MBDia
MF_TmulMdia | multiply the transpose of a matrix by a diagonal matrix: MC = MAT * MBDia
MFdia_mulM | multiply a diagonal matrix by a general matrix: MC = MADia * MB
MFdia_mulMT | multiply a diagonal matrix by the transpose of a general matrix: MC = MADia * MBT

Back to Table of Contents

##

10. Linear Algebra

There are three groups of linear algebra functions. The first group consists of "easy-to-use" versions which can be used as black-box functions without caring about their internal working. The second group consists of functions for LU decomposition and its applications. The third group, finally, is devoted to Singular Value Decomposition (SVD). Except for the functions based on SVD, the linear algebra functions are available both for real and for complex matrices.
Here are the "easy-to-use" versions of linear algebra functions:

MF_solve | solve simultaneous linear equations (using LU decomposition)
MF_inv | invert a matrix
MF_det | determinant of a matrix
MF_solveBySVD | solve simultaneous linear equations, using Singular Value Decomposition
MF_safeSolve | tries first solution by LUD; if that fails, SVD is done

Now some functions for explicit LU decomposition and for treatment of LU decomposed matrices:

MF_LUdecompose | decompose into LU form
MF_LUDresult | check if MF_LUdecompose was successful
MF_LUDsetEdit | set editing threshold for MF_LUdecompose; may be used to work around singularities
MF_LUDgetEdit | retrieve currently set threshold
MF_LUsolve | solve simultaneous linear equations, given the matrix in LU form
MF_LUimprove | improve the accuracy of the solution of an LU-decomposed linear system by iteration
MF_LUinv | invert matrix already composed into LU form
MF_LUdet | determinant of matrix already composed into LU form

Singular Value Decomposition and related functions are offered as:

MF_SVdecompose | Singular Value Decomposition
MF_SVsolve | solve SV-decomposed set of linear equations
MF_SVDsetEdit | set threshold for Singular Value editing
MF_SVDgetEdit | retrieve 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_FFTtoC | Forward Fast Fourier Transform (FFT) of a real matrix; the result is a cartesian complex matrix
MF_FFT | Forward and backward FFT of real matrices; using symmetry relations, the complex result is packed into a real matrix of the same size as the input matrix
MCF_FFT | Forward and backward FFT of complex matrices
MF_convolve | Convolution with a spatial response function
MF_deconvolve | Deconvolution
MF_filter | Spatial filtering
MF_autocorr | Spatial autocorrelation
MF_xcorr | Spatial cross-correlation
MF_spectrum | Spatial frequency spectrum

Back to Table of Contents

##

13. Data Fitting

MatrixLib provides a broad range of data fitting functions for various classes of model functions. Let us first show you an overview over the available functions, before we describe the various classes of model functions and their treatment in OptiVec fitting functions in detail.

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_linfit | fit X-Y-Z data to a function linear in its parameters
MF_linfitwW | the same with non-equal weighting of individual data points
MF_nonlinfit | fit X-Y-Z data to an arbitrary, possibly non-linear function
MF_nonlinfitwW | the same for non-equal data-point weighting
MF_multiLinfit | fit multiple X-Y-Z data sets to one common linear function
MF_multiLinfitwW | the same for non-equal data-point weighting
MF_multiNonlinfit | fit 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:

- the Levenberg-Marquardt method, and the
- Downhill-Simplex method by Nelder and Mead.

As a starting-point, it is normally a good idea to choose a combination of both (choose FitOptions.LevelOfMethod = 3, see below).
The fundamental difference between linear and non-linear data fitting is reflected also in the required formulation of the model functions. In contrast to the linear case, here it is not the individual basis functions which are needed. Rather, the model function will be called by VF_nonlinfit with the whole X-vector as input argument and has to return the whole Y-vector. For the above non-linear sine and cosine example, this would 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] );
}

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

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 MZ; | measured data z=f(x,y)
fMatrix MInvVar; | 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_getBestValues | best set of parameters found so far
VF_nonlinfit_getChi2 | the best figure-of-merit (c2, chi-square) obtained so far
VF_nonlinfit_getTestDir | returns 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_getTestPar | index of the parameter currently under "breakout" investigation
VF_nonlinfit_getTestRun | index of the current "breakout" test run (for each fitted parameter, one test run is performed)
VF_nonlinfit_stop | stops 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_print | print a matrix to the screen (without paging or row cut-off); (DOS, EasyWin and Delphi only)
MF_fprint | print a matrix in ASCII format to a stream
MF_store | store in binary format
MF_recall | retrieve in binary format
MF_write | write in ASCII format in a stream
MF_read | read from an ASCII file

Back to Table of Contents

##

15. Graphical Representation of Matrices

True 3D-plotting functions will be included in future versions. For now, only color-density plots are available. In these plots, each data value is translated into a color value by linear interpolation between two colors, specified as mincolor and maxcolor.

MF_xyzAutoDensityMap | Color density map for z=f(x,y) with automatic scaling of the x and y axes and of the color density scale between mincolor and maxcolor
MF_xyzDataDensityMap | z=f(x,y) color density map, plotted into an existing axis frame, and using the color density scale set by the last call to an AutoDensityMap function
MF_zAutoDensityMap | Color density map for z=f(i,j) with automatic scaling of the x and y axes and of the color density scale between mincolor and maxcolor. i and j are the indices in x and y direction, respectively
MF_zDataDensityMap | Color density map for z=f(i,j), plotted into an existing axis frame, and using the color density scale set by the last call to an AutoDensityMap function
M_setDensityBounds | Set a color scale for matrix color-density plots.
M_setDensityMapBounds | Set a color scale and draw an X-Y coordinate system for matrix color-density plots.
M_findDensityMapBounds | Calculate a color scale and draw an X-Y coordinate system for matrix color-density plots, ensuring that the grid lines of the coordinate system correspond to exact (rather than only rounded) values.

Back to Table of Contents

##

16. Alphabetical Reference of MatrixLib

This chapter describes, in alphabetical order, all MatrixLib functions. Similarly to the indexing of the vector functions in FUNCREF.HTM, the MF_ or M_ prefix is neglected in the ordering of entries. The particles "Row_", "Rows_", "Col_", "Cols_", "Dia_", and "Trd_", however, are fully taken into account. For example, "MF_Rows_" functions will come after all "MF_Row_" functions. While most MatrixLib functions have the prefixes MF_ or M_, please note that some - notably the X-Y fitting functions - have the prefix VF_ as a reminder that they actually work on vectors, even if they rely on matrix methods and form a part of MatrixLib. In cases where both the VF_ and the MF_ versions exist, contrary to the alphabetical order the VF_ version is described first, as it is the simpler one.

MF_addM | MD_addM | ME_addM
MFs_addM | MDs_addM | MEs_addM
MCF_addM | MCD_addM | MCE_addM
Function | element-wise addition of two matrices
Syntax C/C++ | #include <MFstd.h> void MF_addM( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len ); void MFs_addM( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_addM( MC, MA, MB:fMatrix MC; ht, len:UInt ); procedure MFs_addM( MC, MA, MB:fMatrix MC; ht, len:UInt; C:Single );
Description | normal version: MCij = MAij + MBij scaled version: MCij = C * (MAij + MBij)
See also | MF_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
Function | element-wise addition of one matrix and the transpose of another
Syntax C/C++ | #include <MFstd.h> void MF_addMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len ); void MFs_addMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_addMT( MC, MA, MB:fMatrix MC; ht, len:UInt ); procedure MFs_addMT( MC, MA, MB:fMatrix MC; ht, len:UInt; C:Single );
Description | normal version: MCij = MAij + MBTji scaled version: MCij = C * (MAij + MBTji)
See also | MF_addM, MF_subMT, chapter 9

MF_autocorr | MD_autocorr | ME_autocorr
Function | Spatial autocorrelation function
Syntax C/C++ | #include <MFstd.h> void MF_autocorr( fMatrix MY, fMatrix MX, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_autocorr( MY, MX:fMatrix; ht, len:UInt );
Description | The spatial autocorrelation function (SACF) of MX is calculated and stored in MY in wrap-around order in both dimensions: The row elements MYi,0 to MYi,len/2-1 contain the SACF for zero and positive x lags. Beginning with the most negative lag in MYi,len/2+1, the elements up to MYi,len-1 contain the SACF for negative lags. Since this function assumes MX to be periodic, the SACF for the most positive lag is identical to the SACF for the most negative lag. This element is stored as Yi,len/2. Similarly, the column elements MY0,j to MYlen/2-1,j contain the SACF for zero and positive y lags. Beginning with the most negative lag in MYlen/2+1,j, the elements up to MYlen-1,j contain the SACF for negative lags. To get the SACF into normal order, you may call MF_Rows_rotate( MY, ht, len, len/2 ); MF_Cols_rotate( MY, ht, len, ht/2 ); After that, the zero point is at the position MYht/2,len/2. In case MX is non-periodic, you should avoid end effects by the methods described in connection with MF_convolve. Both ht and len must be integer powers of 2. About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM.
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_autocorr is based) complains "Size must be an integer power of 2" and the program is aborted.
See also | MF_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
Function | Copy a matrix into a "block" of another matrix
Syntax C/C++ | #include <MFstd.h> void MF_block_equM( fMatrix MDest, unsigned destHt, unsigned destLen, unsigned firstRow, unsigned firstCol, fMatrix MSrce, unsigned srceHt, unsigned srceLen );
Pascal/Delphi | uses MFstd; procedure MF_block_equM( MDest:fMatrix; destHt, destLen, firstRow, firstCol:UInt; MSrce:fMatrix; srceHt, srceLen:UInt );
Descriptions | MDesti+firstRow, j+firstCol = MSrcei, j, i=0,...,srceHt-1; j=0,...,srceLen-1
See also | MF_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
Function | Copy the transpose of a matrix into a "block" of another matrix
Syntax C/C++ | #include <MFstd.h> void MF_block_equMT( fMatrix MDest, unsigned destHt, unsigned destLen, unsigned firstRow, unsigned firstCol, fMatrix MSrce, unsigned srceHt, unsigned srceLen );
Pascal/Delphi | uses MFstd; procedure MF_block_equMT( MDest:fMatrix; destHt, destLen, firstRow, firstCol:UInt; MSrce:fMatrix; srceHt, srceLen:UInt );
Descriptions | MDesti+firstRow, j+firstCol = MSrcej, i, i=0,...,srceLen-1; j=0,...,srceHt-1
See also | MF_block_equM, MF_equMblockT, MF_submatrix_equM, chapter 5

M_CDtoCF | M_CDtoCE
M_CEtoCF | M_CEtoCD
M_CFtoCD | M_CFtoCE
Function | Data type conversions. See M_FtoD.

MF_Col_addC | MD_Col_addC | ME_Col_addC
MCF_Col_addC | MCD_Col_addC | MCE_Col_addC
Function | add a constant to all elements of one column
Syntax C/C++ | #include <MFstd.h> void MF_Col_addC( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Col_addC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
Description | MAi,iCol += C, i=0,...,ht-1
See also | MF_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
Function | add a vector to a column
Syntax C/C++ | #include <MFstd.h> void MF_Col_addV( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_addV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
Description | MAi,iCol += Xi, i=0,...,ht-1
See also | MF_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
Function | delete one column from a matrix
Syntax C/C++ | #include <MFstd.h> void MF_Col_delete( fMatrix MB, fMatrix MA, unsigned htA, unsigned lenA, unsigned iCol );
Pascal/Delphi | uses MFstd; procedure MF_Col_delete( MB, MA:fMatrix; htA, lenA, iCol:UInt );
Description | MBi,j = MAi,j, i=0,..htA-1, j=0,..iCol-1 MBi,j = MAi,j+1, i=0,...,htA-1, j=iCol,...,lenA-2 The parameters htA and lenA refer to the input matrix
See also | MF_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
Function | divide all elements of one column by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Col_divC( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Col_divC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
Description | MAi,iCol /= C, i=0,...,ht-1
See also | MF_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
Function | Reverse division: divide a constant by a column
Syntax C/C++ | #include <MFstd.h> void MF_Col_divrC( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Col_divrC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
Description | MAi,iCol = C / MAi,iCol, i=0,...,ht-1
See also | MF_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
Function | Reverse division: divide a vector by a column (element-wise)
Syntax C/C++ | #include <MFstd.h> void MF_Col_divrV( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_divrV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
Description | MAi,iCol = Xi / MAi,iCol, i=0,...,ht-1
See also | MF_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
Function | element-wise division of a column by a vector
Syntax C/C++ | #include <MFstd.h> void MF_Col_divV( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_divV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
Description | MAi,iCol /= Xi, i=0,...,ht-1
See also | MF_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
Function | set all elements of one column to zero
Syntax C/C++ | #include <MFstd.h> void MF_Col_equ0( fMatrix MA, unsigned ht, unsigned len, unsigned iCol );
Pascal/Delphi | uses MFstd; procedure MF_Col_equ0( MA:fMatrix; ht, len, iCol:UInt );
Description | MAi,iCol = 0, i=0,...,ht-1
See also | MF_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
Function | initialize all elements of one column with a constant
Syntax C/C++ | #include <MFstd.h> void MF_Col_equC( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Col_equC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
Description | MAi,iCol = C, i=0,...,ht-1
See also | MF_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
Function | copy a vector into one column
Syntax C/C++ | #include <MFstd.h> void MF_Col_equV( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_equV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
Description | MAi,iCol = Xi, i=0,...,ht-1
See also | MF_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
Function | copy one column into a vector
Syntax C/C++ | #include <MFstd.h> void MF_Col_extract( fVector Y, fMatrix MA, unsigned ht, unsigned len, unsigned iCol );
Pascal/Delphi | uses MFstd; procedure MF_Col_extract( Y:fVector; MA:fMatrix; ht, len, iCol:UInt );
Description | Yi = MAi,iCol, i=0,...,ht-1
See also | MF_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
Function | augment a matrix by insertion of one column
Syntax C/C++ | #include <MFstd.h> void MF_Col_insert( fMatrix MB, fMatrix MA, unsigned htB, unsigned lenB, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_insert( MB, MA:fMatrix; htB, lenB, iCol:UInt; X:fVector );
Description | MBi,j = MAi,j, i=0,...,htB-1, j=0,...,iCol-1 MBi,iCol = Xi, i=0,...,htB-1 MBi,j = MAi,j-1, i=0,...,htB-1, j=iCol,...,lenB-1 The parameters htB and lenB refer to the output matrix
See also | MF_Col_delete, chapter 5

MF_Col_mulC | MD_Col_mulC | ME_Col_mulC
MCF_Col_mulC | MCD_Col_mulC | MCE_Col_mulC
Function | multiply all elements of one column by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Col_mulC( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Col_mulC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
Description | MAi,iCol *= C, i=0,...,ht-1
See also | MF_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
Function | element-wise multiplication of a column by a vector
Syntax C/C++ | #include <MFstd.h> void MF_Col_mulV( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_mulV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
Description | MAi,iCol *= Xi, i=0,..,ht-1
See also | MF_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
Function | subtract a constant from all elements of one column
Syntax C/C++ | #include <MFstd.h> void MF_Col_subC( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Col_subC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
Description | MAi,iCol -= C, i=0,..,ht-1
See also | MF_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
Function | reverse subtraction: a constant minus one column
Syntax C/C++ | #include <MFstd.h> void MF_Col_subrC( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Col_subrC( MA:fMatrix; ht, len, iCol:UInt; C:Single );
Description | MAi,iCol = C - MAi,iCol, i=0,..,ht-1
See also | MF_Col_addC, MF_Row_subC, MF_Col_subrV, MF_Col_subC, chapter 6

MF_Col_subV | MD_Col_subV | ME_Col_subV
MCF_Col_subV | MCD_Col_subV | MCE_Col_subV
Function | subtract a vector from a column (element-wise)
Syntax C/C++ | #include <MFstd.h> void MF_Col_subV( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_subV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
Description | MAi,iCol -= Xi, i=0,..,ht-1
See also | MF_Col_subC, MF_Row_subV, MF_Col_subrC, chapter 6

MF_Col_subrV | MD_Col_subrV | ME_Col_subrV
MCF_Col_subrV | MCD_Col_subrV | MCE_Col_subrV
Function | reverse subtraction: a vector minus one column (element-wise)
Syntax C/C++ | #include <MFstd.h> void MF_Col_subrV( fMatrix MA, unsigned ht, unsigned len, unsigned iCol, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Col_subrV( MA:fMatrix; ht, len, iCol:UInt; X:fVector );
Description | MAi,iCol = Xi - MAi,iCol, i=0,..,ht-1
See also | MF_Col_subV, MF_Row_subrV, MF_Col_subrC, chapter 6

MF_Cols_absmax | MD_Cols_absmax | ME_Cols_absmax
MCF_Cols_absmax | MCD_Cols_absmax | MCE_Cols_absmax
Function | store the absolute maxima of all individual columns in a row vector
Syntax C/C++ | #include <MFstd.h> void MF_Cols_absmax( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_absmax( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The maximum absolute value of each column j is stored as the element Yj for j=0,..,len-1
See also | MF_Cols_max, MF_Cols_absmin, MF_Rows_absmax, MF_Dia_absmax, chapter 7

MF_Cols_absmin | MD_Cols_absmin | ME_Cols_absmin
MCF_Cols_absmin | MCD_Cols_absmin | MCE_Cols_absmin
Function | store the absolute minima of all individual columns in a row vector
Syntax C/C++ | #include <MFstd.h> void MF_Cols_absmin( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_absmin( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The minimum absolute value of each column j is stored as the element Yj for j=0,..,len-1
See also | MF_Cols_min, MF_Cols_absmax, MF_Rows_absmin, MF_Dia_absmin, chapter 7

MF_Cols_add | MD_Cols_add | ME_Cols_add
MCF_Cols_add | MCD_Cols_add | MCE_Cols_add
Function | make one column the sum of itself and another column
Syntax C/C++ | #include <MFstd.h> void MF_Cols_add( fMatrix MA, unsigned ht, unsigned len, unsigned destCol, unsigned sourceCol );
Pascal/Delphi | uses MFstd; procedure MF_Cols_add( MA:fMatrix; ht, len, destCol, sourceCol:UInt );
Description | MAi,destCol += MAi,sourceCol, i=0,..,ht-1
See also | MF_Cols_sub, MF_Cols_Cadd, MF_Cols_lincomb, chapter 8

MF_Cols_Cadd | MD_Cols_Cadd | ME_Cols_Cadd
MCF_Cols_Cadd | MCD_Cols_Cadd | MCE_Cols_Cadd
Function | make one column the sum of itself and another column, scaled by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Cols_Cadd( fMatrix MA, unsigned ht, unsigned len, unsigned destCol, unsigned sourceCol, float C );
Pascal/Delphi | uses MFstd; procedure MF_Cols_Cadd( MA:fMatrix; ht, len, destCol, sourceCol:UInt; C:Single );
Description | MAi,destCol += C * MAi,sourceCol, i=0,..,ht-1
See also | MF_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
Function | exchange two columns
Syntax C/C++ | #include <MFstd.h> void MF_Cols_exchange( fMatrix MA, unsigned ht, unsigned len, unsigned i1, unsigned i2 );
Pascal/Delphi | uses MFstd; procedure MF_Cols_exchange( MA:fMatrix; ht, len, i1, i2:UInt );
Description | The elements of the columns i1 and i2 are exchanged.
See also | MF_Rows_exchange, chapter 8

MF_Cols_lincomb | MD_Cols_lincomb | ME_Cols_lincomb
MCF_Cols_lincomb | MCD_Cols_lincomb | MCE_Cols_lincomb
Function | linear combination of two columns
Syntax C/C++ | #include <MFstd.h> void MF_Cols_lincomb( fMatrix MA, unsigned ht, unsigned len, unsigned destCol, float destC, unsigned srceCol, float srceC );
Pascal/Delphi | uses MFstd; procedure MF_Cols_lincomb( MA:fMatrix; ht, len:UInt; destCol:UInt; destC:Single; srceCol:Uint; srceC:Single );
Description | MAi,destCol = destC * MAi,destCol+ srceC * MAi,srceCol, i=0,..,ht-1
See also | MF_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
Function | store the maxima of all individual columns in a row vector
Syntax C/C++ | #include <MFstd.h> void MF_Cols_max( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_max( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The maximum value of each column j is stored as the element Yj for j=0,..,len-1
See also | MF_Cols_absmax, MF_Cols_min, MF_Rows_max, chapter 7

MF_Cols_min | MD_Cols_min | ME_Cols_min
MCF_Cols_min | MCD_Cols_min | MCE_Cols_min
Function | store the minima of all individual columns in a row vector
Syntax C/C++ | #include <MFstd.h> void MF_Cols_min( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_min( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The minimum value of each column j is stored as the element Yj for j=0,..,len-1
See also | MF_Cols_absmax, MF_Cols_min, MF_Rows_max, chapter 7

MF_Cols_prod | MD_Cols_prod | ME_Cols_prod
MCF_Cols_prod | MCD_Cols_prod | MCE_Cols_prod
Function | products over all elements of each individual column, stored in a row vector
Syntax C/C++ | #include <MFstd.h> void MF_Cols_prod(fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_prod(Y:fVector; MA:fMatrix; ht, len:UInt );
Description | Yj = prod( MAi,j, i=0,..,ht-1), j=0,..,len-1
See also | MF_Cols_runprod, MF_Cols_sum, chapter 7

MF_Cols_reflect | MD_Cols_reflect | ME_Cols_reflect
Function | Derive the second halves of all columns from their first halves by reflection at the horizontal line through the center of the matrix.
Syntax C/C++ | #include <MFstd.h> void MF_Cols_reflect( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_reflect( MA:fMatrix; ht, len:UInt );
Description | MAht-i-1,j = MAi, j, i=0,..(ht-1)/2; j=0,..,len-1
See also | MF_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
Function | rotate all columns by a specified number of positions; thereby, whole rows are moved
Syntax C/C++ | #include <MFstd.h> void MF_Cols_rotate( fMatrix MA, unsigned ht, unsigned len, int pos );
Pascal/Delphi | uses MFstd; procedure MF_Cols_rotate( MA:fMatrix; ht, len:UInt; pos:Integer );
Description | MAi,j = MAht-pos+i, j, i=0,..,pos-1 MAi,j = MAi-pos, j, i=pos,...,ht-1
See also | MF_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
Function | running product over column elements
Syntax C/C++ | #include <MFstd.h> void MF_Cols_runprod( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_runprod( MA:fMatrix; ht, len:UInt );
Description | For all columns separately, each element is the product of itself and all preceding elements. This function should be used with care: overflow is easily reached, and underflow may lead to all elements from a certain position on being zero.
See also | MF_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
Function | running sum over column elements
Syntax C/C++ | #include <MFstd.h> void MF_Cols_runsum( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_runsum( MA:fMatrix; ht, len:UInt );
Description | For all columns separately, each element is the sum of itself and all preceding elements.
See also | MF_Cols_sum, MF_Rows_runsum, chapter 7

MF_Cols_sub | MD_Cols_sub | ME_Cols_sub
MCF_Cols_sub | MCD_Cols_sub | MCE_Cols_sub
Function | subtract one column from another and store the result back into the subtrahend
Syntax C/C++ | #include <MFstd.h> void MF_Cols_sub( fMatrix MA, unsigned ht, unsigned len, unsigned destCol, unsigned sourceCol );
Pascal/Delphi | uses MFstd; procedure MF_Cols_sub( MA:fMatrix; ht, len, destCol, sourceCol:UInt; );
Description | MAi,destCol -= MAi,sourceCol, i=0,..,ht-1
See also | MF_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
Function | sums over all columns, returned in a row vector
Syntax C/C++ | #include <MFstd.h> void MF_Cols_sum( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Cols_sum( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | Yj = sum( MAi,j, i=0,..,ht-1), j=0,..,len-1
See also | MF_Cols_prod, MF_Cols_runsum, chapter 7

MCF_conj | MCD_conj | MCE_conj
Function | complex conjugate
Syntax C/C++ | #include <MFstd.h> void MCF_conj( cfMatrix MB, cfMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MCF_conj( MB, MA:cfMatrix; ht, len:UInt );
Description | MBij.Re = MAij.Re MBij.Im = -MAij.Im
See also | MCF_neg, chapter 3

MF_convolve | MD_convolve | ME_convolve
Function | convolution with a spatial response function
Syntax C/C++ | #include <MFstd.h> void MF_convolve( fMatrix MY, fMatrix MFlt, fMatrix MX, fMatrix MRsp, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_convolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UInt );
Description | The convolution of MX with the response function MRsp is calculated and stored in MY. A filter MFlt is also calculated. If more than one matrix is to be convolved with the same MRsp, use MF_convolve only once and use MF_filter for the other matrices. The response has to be stored in MRsp in wrap-around order in both dimensions: in each row i of MRsp, the response for zero and positive x-values is stored in MRspi,0 to MRspi,len/2 and the response for negative x-values (beginning with the most negative x) in MRspi,len/2+1 to MRspi,len-1. Similarly, in each column of MRsp, the response for zero and positive y-values is stored in MRsp0,j to MRsplen/2,j and the response for negative y-values (beginning with the most negative y) in MRsplen/2+1,j to MRsplen-1,j. You may wish to use MF_Rows_rotate and MF_Cols_rotate, or MF_Rows_reflect and MF_Cols_reflect to achieve this wrap-around order and to construct the response matrix. The result of the convolution appears scaled with the sum of all elements of MRsp. Normally, therefore, MRsp should be normalized to 1.0. MX, MY, MRsp, and MFlt must all be of the same dimensions. Both len and ht have to be integer powers of 2. MX may be overwritten by MY, MRsp may be overwritten by MFlt, but MX and MFlt as well as MY and MRsp have to be distinct from each other. As in the one-dimensional case, the treatment of round-off errors in the construction of MFlt may be modified by VF_setRspEdit. The input matrix is assumed to be periodic in both dimensions. See the description of VF_convolve on how to avoid end effects, in case it is not periodic. About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM.
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_convolve is based) complains "Size must be an integer power of 2" and the program is aborted.
See also | MF_deconvolve, MF_FFT, chapter 12

MF_cprint | MD_cprint | ME_cprint
MCF_cprint | MCD_cprint | MCE_cprint
Function | print a matrix to the screen (DOS and Win32-console only; not for Visual C++)
Syntax C/C++ | #include <MFstd.h> void MF_cprint( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_cprint( MA:fMatrix; ht, len:UInt );
Description | The matrix MA is printed to the screen. Each line corresponds to one row of the matrix. The lines are numbered. If necessary, rows are cut off at the screen boundaries. If there are more rows than screen lines, proper paging is applied. This family of functions is available only for DOS and Win32 console applications with the Borland compilers. It should not be used within TurboVision DOS programs.
Error handling | If the number of columns exceeds the maximum number of entries possible in the current text mode, an error message "Cannot use requested format (too many entries per line)!" is generated; in this case, the rows are truncated.
See also | MF_fprint, VF_cprint, chapter 14

MF_deconvolve | MD_deconvolve | ME_deconvolve
Function | spatial deconvolution, edge sharpening
Syntax C/C++ | #include <MFstd.h> void MF_deconvolve( fMatrix MY, fMatrix MFlt, fMatrix MX, fMatrix MRsp, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_deconvolve( MY, MFlt, MX, MRsp:fMatrix; ht, len:UInt );
Description | MX is assumed to be the result of a convolution of some "true" profile with the response function MRsp; a deconvolution is attempted and stored in MY. A filter MFlt is also calculated; if more than one matrix is to be deconvolved with the same MRsp, use MF_deconvolve only once and use the filter MFlt thus obtained to deconvolve other matrices by calling MF_filter. The response has to be stored in the wrap-around order described above for MF_convolve. As for MF_convolve, MX, MY, MRsp, and MFlt must all be of the same dimensions, which have to be integer powers of 2. MX may be overwritten by MY, MRsp may be overwritten by MFlt, but MX and MFlt as well as MY and MRsp have to be distinct from each other. Mathematically, MFlt is the inverse of the Fourier transform of MRsp. If the Fourier transform of MRsp contains elements equal to zero, all information is lost for the respective frequency and no reconstruction is possible. The best one can do in this case is to accept this loss and to deconvolve only up to those frequencies where still something is left to be reconstructed. You are therefore advised not to use this function blindly but rather to inspect the Fourier transform of MRsp and decide what to do on the basis of your specific application. If you wish to use this function nevertheless, you may rely on the automatic editing of the filter, built into MF_deconvolve. Thereby, MFlt is set to zero (instead of infinity) at those frequences where all information has been lost. You may set the threshold for this implicit editing by VF_setRspEdit. In order to retrieve the threshold actually set, use VF_getRspEdit. (These two functions are shared between the one- and two-dimensional FFT functions and described in FUNCREF.HTM.) This deconvolution is based on the implicit assumption that MX is periodic; if this is not the case, see the description of VF_convolve about how to avoid end effects.
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_deconvolve is based) complains "Size must be an integer power of 2" and the program is aborted. If, by VF_setRspEdit, you specified Trunc.Re = Trunc.Im = 0, SING errors may occur that are handled by setting MFlt to ±HUGE_VAL at the respective frequency. During multiplication with the transform of MX, this may lead to unhandled floating-point overflow errors (in case your guess of MRsp was wrong and there is some information left at the frequencies where you thought it was not). About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM.
See also | MF_convolve, MF_FFT, chapter 12

MF_det | MD_det | ME_det
MCF_det | MCD_det | MCE_det
Function | determinant of a square matrix
Syntax C/C++ | #include <MFstd.h> float MF_det( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_det( MA:fMatrix; len:UInt ):Single;
Description | The determinant of MA is calculated. For large matrices, this is done via LU decomposition. For small matrices, individual formulae are applied.
Return value | determinant of the matrix
See also | MF_LUdecompose, MF_solve, chapter 10

MF_Dia_absmax | MD_Dia_absmax | ME_Dia_absmax
MCF_Dia_absmax | MCD_Dia_absmax | MCE_Dia_absmax
Function | absolute maximum of the elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> float MF_Dia_absmax( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_Dia_absmax( MA:fMatrix; len:UInt ):Single;
Description | The maximum absolute value of all elements MAi,i is returned as a scalar
Return value | absolute maximum of the diagonal
See also | MF_Dia_max, MF_Dia_absmin, chapter 7

MF_Dia_absmin | MD_Dia_absmin | ME_Dia_absmin
MCF_Dia_absmin | MCD_Dia_absmin | MCE_Dia_absmin
Function | absolute minimum of the elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> float MF_Dia_absmin( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_Dia_absmin( MA:fMatrix; len:UInt ):Single;
Description | The minimum absolute value of all elements MAi,i is returned as a scalar
Return value | absolute minimum of the diagonal
See also | MF_Dia_min, MF_Dia_absmax, chapter 7

MF_Dia_addC | MD_Dia_addC | ME_Dia_addC
MCF_Dia_addC | MCD_Dia_addC | MCE_Dia_addC
Function | add a constant to all elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> void MF_Dia_addC( fMatrix MA, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_Dia_addC( MA:fMatrix; len:UInt; C:Single );
Description | MAi,i += C, i=0,...,len-1
See also | MF_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
Function | element-wise addition of a vector to the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> void MF_Dia_addV( fMatrix MA, unsigned len, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Dia_addV( MA:fMatrix; len:UInt; X:fVector );
Description | MAi,i += Xi, i=0,...,len-1
See also | MF_Dia_addC, MF_Dia_subV, chapter 6

MF_Dia_divC | MD_Dia_divC | ME_Dia_divC
MCF_Dia_divC | MCD_Dia_divC | MCE_Dia_divC
Function | divide all elements of the diagonal of a square matrix by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Dia_divC( fMatrix MA, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_Dia_divC( MA:fMatrix; len:UInt; C:Single );
Description | MAi,i /= C, i=0,...,len-1
See also | MF_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
Function | reverse division: divide a constant by the elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> void MF_Dia_divrC( fMatrix MA, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_Dia_divrC( MA:fMatrix; len:UInt; C:Single );
Description | MAi,i = C / MAi,i, i=0,...,len-1
See also | MF_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
Function | reverse division: divide a vector by the diagonal of a square matrix, storing the result back into the diagonal
Syntax C/C++ | #include <MFstd.h> void MF_Dia_divrV( fMatrix MA, unsigned len, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Dia_divrV( MA:fMatrix; len:UInt; X:fVector );
Description | MAi,i = Xi / MAi,i, i=0,...,len-1
See also | MF_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
Function | element-wise division of the diagonal of a square matrix by a vector
Syntax C/C++ | #include <MFstd.h> void MF_Dia_divV( fMatrix MA, unsigned len, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Dia_divV( MA:fMatrix; len:UInt; X:fVector );
Description | MAi,i / Xi, i=0,...,len-1
See also | MF_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
Function | initialize all elements of the diagonal of a square matrix with zero
Syntax C/C++ | #include <MFstd.h> void MF_Dia_equ0( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Dia_equ0( MA:fMatrix; len:UInt );
Description | MAi,i = 0, i=0,...,len-1
See also | MF_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
Function | initialize all elements of the diagonal of a square matrix with a constant
Syntax C/C++ | #include <MFstd.h> void MF_Dia_equC( fMatrix MA, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_Dia_equC( MA:fMatrix; len:UInt; C:Single );
Description | MAi,i = C, i=0,...,len-1
See also | MF_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
Function | copy a vector into the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> void MF_Dia_equV( fMatrix MA, unsigned len, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Dia_equV( MA:fMatrix; len:UInt; X:fVector );
Description | MAi,i = Xi, i=0,...,len-1
See also | MF_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
Function | copy the diagonal of a square matrix into a vector
Syntax C/C++ | #include <MFstd.h> void MF_Dia_extract( fVector Y, fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Dia_extract( Y:fVector; MA:fMatrix; len:UInt );
Description | Yi = MAi,i, i=0,...,len-1
See also | MF_Dia_equV, chapter 3, chapter 6

MF_Dia_max | MD_Dia_max | ME_Dia_max
MCF_Dia_max | MCD_Dia_max | MCE_Dia_max
Function | maximum of all elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> float MF_Dia_max( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_Dia_max( MA:fMatrix; len:UInt ):Single;
Description | the largest element of the diagonal is returned as a scalar
Return value | maximum of the diagonal
See also | MF_Dia_absmax, MF_Dia_min, chapter 6, chapter 7

MF_Dia_min | MD_Dia_min | ME_Dia_min
MCF_Dia_min | MCD_Dia_min | MCE_Dia_min
Function | minimum of all elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> float MF_Dia_min( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_Dia_min( MA:fMatrix; len:UInt ):Single;
Description | the smallest or most negative element of the diagonal is returned as a scalar
Return value | minimum of the diagonal
See also | MF_Dia_absmin, MF_Dia_max, chapter 6, chapter 7

MF_Dia_mulC | MD_Dia_mulC | ME_Dia_mulC
MCF_Dia_mulC | MCD_Dia_mulC | MCE_Dia_mulC
Function | multiply all elements of the diagonal of a square matrix by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Dia_mulC( fMatrix MA, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_Dia_mulC( MA:fMatrix; len:UInt; C:Single );
Description | MAi,i *= C, i=0,...,len-1
See also | MF_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
Function | element-wise multiplication of the diagonal of a square matrix by a vector
Syntax C/C++ | #include <MFstd.h> void MF_Dia_mulV( fMatrix MA, unsigned len, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Dia_mulV( MA:fMatrix; len:UInt; X:fVector );
Description | MAi,i *= Xi, i=0,...,len-1
See also | MF_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
Function | product of all elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> float MF_Dia_prod( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_Dia_prod( MA:fMatrix; len:UInt ):Single;
Description | the product of the diagonal elements is returned as a scalar
Return value | product of the diagonal elements
See also | MF_Dia_sum, chapter 7

MF_Dia_subC | MD_Dia_subC | ME_Dia_subC
MCF_Dia_subC | MCD_Dia_subC | MCE_Dia_subC
Function | subtract a constant from all elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> void MF_Dia_subC( fMatrix MA, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_Dia_subC( MA:fMatrix; len:UInt; C:Single );
Description | MAi,i -= C, i=0,...,len-1
See also | MF_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
Function | reverse subtraction: a constant minus the elements of the diagonal of a square matrix, storing the result back into the diagonal
Syntax C/C++ | #include <MFstd.h> void MF_Dia_subrC( fMatrix MA, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_Dia_subrC( MA:fMatrix; len:UInt; C:Single );
Description | MAi,i = C - MAi,i, i=0,...,len-1
See also | MF_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
Function | reverse subtraction: subtract the elements of the diagonal of a square matrix from corresponding elements of a vector, storing the result back into the diagonal
Syntax C/C++ | #include <MFstd.h> void MF_Dia_subrV( fMatrix MA, unsigned len, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Dia_subrV( MA:fMatrix; len:UInt; X:fVector );
Description | MAi,i = Xi - MAi,i, i=0,...,len-1
See also | MF_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
Function | element-wise subtraction of a vector from the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> void MF_Dia_subV( fMatrix MA, unsigned len, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Dia_subV( MA:fMatrix; len:UInt; X:fVector );
Description | MAi,i -= Xi, i=0,...,len-1
See also | MF_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
Function | sum over all elements of the diagonal of a square matrix
Syntax C/C++ | #include <MFstd.h> float MF_Dia_sum( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_Dia_sum( MA:fMatrix; len:UInt ):Single;
Description | the elements of the diagonal are summed up and returned as a scalar
Return value | sum over the diagonal elements
See also | MF_Dia_prod, chapter 7

MF_divC | MD_divC | ME_divC
MCF_divC | MCD_divC | MCE_divC
MCF_divReC | MCD_divReC | MCE_divReC
Function | divide all matrix elements by a constant
Syntax C/C++ | #include <MFstd.h> void MF_divC( fMatrix MB, fMatrix MA, unsigned ht, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_divC( MB, MA:fMatrix; ht, len:UInt; C:Single );
Description | Mi,j /= C, i=0,...,ht-1; j=0,..,len-1
See also | MF_mulC, chapter 3

M_DtoF | M_DtoE
Function | Data type conversions. See M_FtoD.

MF_element | MD_element | ME_element
MCF_element | MCD_element | MCE_element
Function | read-only access to a matrix element
Syntax C/C++ | #include <MFstd.h> float MF_element( fMatrix X, unsigned ht, unsigned len, unsigned m, unsigned n ); fComplex MCF_element( cfMatrix X, unsigned ht, unsigned len, unsigned m, unsigned n );
Pascal/Delphi | uses MFstd; function MF_element( MA:fMatrix; ht, len, m, n:UInt ); procedure MCF_element( var RetVal:fComplex; MA:cfMatrix; ht, len, m, n:UInt );
Description | The element MAm,n is returned. Pascal/Delphi only: As fComplex return values are not possible, the MCF_ version stores MAm,n into the variable RetVal. This function is needed to read elements of dynamically allocated matrices, for which older versions of Borland C++ had a pointer arithmetics bug, and Pascal/Delphi - unlike C - does not provide an own mechanism at all. MF_element is "read-only". This means, you c a n n o t write something like MF_element( MX, ht, len, 3, 4 ) := 5; Write access to individual matrix elements is provided by MF_Pelement
Return value | the matrix element m,n (except complex version in Pascal/Delphi)
See also | MF_Pelement, chapter 2

MFsym_eigenvalues | MDsym_eigenvalues | MEsym_eigenvalues
Function | Eigenvalues and/or Eigenvectors of a real symmetric matrix
Syntax C/C++ | #include <MFstd.h> void MFsym_eigenvalues( fVector EigVals, fMatrix EigVecs, fMatrix MA, unsigned len, int CalcEigenVec );
Pascal/Delphi | uses MFstd; procedure MFsym_eigenvalues( EigVals:fVector; EigVecs, MA:fMatrix; len:UInt; CalcEigenVec:IntBool );
Description | The eigenvalues, with or without the eigenvectors, of MA are calculated. This function is for symmetric real matrices only! It takes the following arguments: EigVals: a vector in which the eigenvalues will be returned EigVecs: a matrix whose columns will be filled with the eigenvectors MA: the input matrix, which may or may not be overwritten by EigVecs len: the length of the rows (which is the same as the height of the columns, as MA must be a symmetric square matrix) CalcEigenVec: an int or IntBool, deciding if only the eigenvalues are needed (CalcEigenVec = FALSE or 0), or if the eigenvectors are desired as well (CalcEigenVec = TRUE or 1). Calculating the eigenvalues alone, without the eigenvectors, can speed up the calculation by up to a factor of two.
See also | chapter 10, chapter 11

MF_equ0 | MD_equ0 | ME_equ0
MCF_equ0 | MCD_equ0 | MCE_equ0
Function | initialize a matrix with all elements set to 0
Syntax C/C++ | #include <MFstd.h> void MF_equ0( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_equ0( MA:fMatrix; ht, len:UInt );
Description | MAi,j = 0
See also | MF_equ1, MF_equM, chapter 3

MF_equ1 | MD_equ1 | ME_equ1
MCF_equ1 | MCD_equ1 | MCE_equ1
Function | identity matrix
Syntax C/C++ | #include <MFstd.h> void MF_equ1( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_equ1( MA:fMatrix; len:UInt );
Description | MAi,i = 1 MAi,j = 0, i != j
See also | MF_equ0, MF_equm1, chapter 3

MF_equM | MD_equM | ME_equM
MCF_equM | MCD_equM | MCE_equM
Function | make one matrix the copy of another
Syntax C/C++ | #include <MFstd.h> void MF_equM( fMatrix MB, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_equM( MB, MA:fMatrix; ht, len:UInt );
Description | MBi,j = MAi,j
See also | MF_transpose, MF_neg, chapter 3

MF_equm1 | MD_equm1 | ME_equm1
MCF_equm1 | MCD_equm1 | MCE_equm1
Function | negative identity matrix
Syntax C/C++ | #include <MFstd.h> void MF_equm1( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_equm1( MA:fMatrix; len:UInt );
Description | MAi,i = -1 MAi,j = 0, i != j
See also | MF_equ0, MF_equ1, chapter 3

MF_equMblock | MD_equMblock | ME_equMblock
MCF_equMblock | MCD_equMblock | MCE_equMblock
Function | Extract a block from a matrix
Syntax C/C++ | #include <MFstd.h> void MF_equMblock( fMatrix MSub, unsigned subHt, unsigned subLen, fMatrix MSrce, unsigned srceHt, unsigned srceLen, unsigned firstRow, unsigned firstCol );
Pascal/Delphi | uses MFstd; procedure MF_equMblock( MSub:fMatrix; subHt, subLen: UInt; MSrce:fMatrix; srceHt, srceLen, firstRow, firstCol:UInt );
Description | MSubi, j = MSrcei+firstRow, j+firstCol, i=0,...,subHt-1; j=0,...,subLen-1
See also | MF_block_equM, MF_equMblockT, MF_submatrix_equM, chapter 5

MF_equMblockT | MD_equMblockT | ME_equMblockT
MCF_equMblockT | MCD_equMblockT | MCE_equMblockT
Function | Extract and transpose a block from a matrix
Syntax C/C++ | #include <MFstd.h> void MF_equMblockT( fMatrix MSub, unsigned subHt, unsigned subLen, fMatrix MSrce, unsigned srceHt, unsigned srceLen, unsigned firstRow, unsigned firstCol );
Pascal/Delphi | uses MFstd; procedure MF_equMblockT( MSub:fMatrix; subHt, subLen: UInt; MSrce:fMatrix; srceHt, srceLen, firstRow, firstCol:UInt );
Description | MSubj, i = MSrcei+firstRow, j+firstCol, i=0,...,subLen-1; j=0,...,subHt-1
See also | MF_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
Function | two-dimensional Fast Fourier Transform
Syntax C/C++ | #include <MFstd.h> void MF_FFT( fMatrix MY, fMatrix MX, unsigned ht, unsigned len, int dir ); void MCF_FFT( cfMatrix MY, cfMatrix MX, unsigned ht, unsigned len, int dir ); void MF_FFTtoC( cfMatrix MY, fMatrix MX, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_FFT( MY, MX:fMatrix; ht, len:UInt; dir:Integer ); procedure MCF_FFT( MY, MX:cfMatrix; ht, len:UInt; dir:Integer ); procedure MF_FFTtoC( MY:cfMatrix; MX:fMatrix; ht, len:UInt );
Description | The Fourier transform of MX is calculated and stored in MY. The forward transform is obtained by setting dir = 1, the inverse (or backward) transform by setting dir = -1. A Fast Fourier Transform algorithm is used that requires both ht and len to be powers of 2. Complex version: Both MX and the output MY are complex matrices. Real-to-complex version: The input matrix MX is real. The output matrix MY is complex. As this function can only perform a forward transform, no argument "dir" is needed. Purely real version: For the forward transform, MX is a real matrix. The output MY is also defined as fMatrix, although it consists of complex numbers. The reason is that, just as in the one-dimensional case, the symmetry properties of two-dimensional FFT allow to store the result in a packed format, fitting into the same memory space as the input matrix. The order of storage in MY is derived from the ordering in the one-dimensional case, with the packing applied first to all rows, then to the columns. The resulting order is indicated in the following table. U means the uncompressed result.
U0,0.Re | U0,len/2.Re | U0,1.Re | U0,1.Im | ··· | U0,len/2-1.Re | U0,len/2-1.Im
Uht/2,0.Re | Uht/2,len/2.Re | U1,1.Re | U1,1.Im | ··· | U1,len/2-1.Re | U1,len/2-1.Im
U1,0.Re | U1,len/2.Re | U2,1.Re | U2,1.Im | ··· | U2,len/2-1.Re | U2,len/2-1.Im
U1,0.Im | U1,len/2.Im | U3,1.Re | U3,1.Im | ··· | U3,len/2-1.Re | U3,len/2-1.Im
··· | ··· | ··· | ··· | ··· | ··· | ···
Uht/2-1,0.Re | Uht/2-1,len/2.Re | ··· | ··· | ··· | ··· | ···
Uht/2-1,0.Im | Uht/2-1,len/2.Im | Uht-1,1.Re | Uht-1,1.Im | ··· | Uht-1,len/2-1.Re | Uht-1,len/2-1.Im
For inverse real-matrix FFT, the input matrix has to be of this packed-complex format, and you get a real matrix. If you prefer to get the result of forward FFT as a true complex matrix, use MF_FFTtoC. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8.
Error handling | If either ht or len is not a power of 2, VF_FFT (on which MF_FFT is based) complains "Size must be an integer power of 2" and the program is aborted.
See also | chapter 12, chapter 4.8 of HANDBOOK.HTM

MF_filter | MD_filter | ME_filter
MCF_filter | MCD_filter | MCE_filter
Function | Spatial frequency filtering
Syntax C/C++ | #include <MFstd.h> void MF_filter( fMatrix MY, fMatrix MX, fMatrix MFlt, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_filter( MY, MX, MFlt:fMatrix; ht, len:UInt );
Description | A spatial frequency filter MFlt is applied to the matrix MX. Internally, this is done by performing a Fourier transform on MX, multiplying the transform with MFlt and transforming the product back into the space domain. Complex versions: MX, MY and the filter MFlt are complex matrices. Real versions: MX and MY are real. MFlt has to be in the packed complex format that is obtained by Fourier transforming a real matrix with MF_FFT (see that function for the description of the packed complex format) or by using MF_convolve. If MX is non-periodic, the edges of the filtered function may be spoiled by wrap-around. See VF_convolve about how to avoid end-effects. As described there for vectors, embed the matrix MX in a larger matrix or remove a possible linear trends in both dimensions. About special versions with the prefixes VFs_ and VFl_, consult chapter 4.8.
Error handling | If either ht or len is not a power of 2, VF_FFT (on which MF_filter is based) complains "Size must be an integer power of 2" and the program is aborted.
See also | MF_FFT, MF_convolve, chapter 12, chapter 4.8 of HANDBOOK.HTM

M_findDensityMapBounds
Function | Calculate a color scale and draw an X-Y coordinate system for matrix color-density plots
Syntax C/C++ | #include <Mgraph.h> void M_findDensityMapBounds( extended xmin, extended xmax, extended ymin, extended ymax, extended zmin, extended zmax, COLORREF mincolor, COLORREF maxcolor );
Pascal/Delphi | uses Mgraph; procedure M_findDensityMapBounds( xmin, xmax, ymin, ymax, zmin, zmax: Extended; mincolor, maxcolor: COLORREF );
Description | Similarly to the function V_findAxes for X-Y vector plots, this function calculates a color scale from the parameters mincolor, maxcolor, zmin and zmax, and prepares an X-Y coordinate system for color-density plots of matrices. If necessary, the x and y ranges are slightly enlarged so as to ensure that the grid-lines correspond to exact (rather than only rounded) values. If zero falls into either or both ranges, it will fall onto a grid line. The user will rarely call this function himself. It is internally called by all functions of the MF_xyzAutoDensityMap and MF_zAutoDensityMap families.
See also | MF_xyzAutoDensityMap, MF_zAutoDensityMap, chapter 15

MF_fprint | MD_fprint | ME_fprint
MCF_fprint | MCD_fprint | MCE_fprint
Function | print a matrix in ASCII format to a stream
Syntax C/C++ | #include <MFstd.h> void MF_fprint( FILE *stream, fMatrix MA, unsigned ht, unsigned len, unsigned linewidth );
Pascal/Delphi | uses MFstd; {Delphi version:} procedure MF_fprint( var Stream:TextFile; MA:fMatrix; ht, len, linewidth:UInt ); {Turbo Pascal version:} procedure MF_fprint( var Stream:Text; MA:fMatrix; ht, len, linewidth:UInt );
Description | The matrix MA is written to stream. Each line corresponds to one row of the matrix. The lines are numbered. If the specified linewidth is too small to write all columns, rows are cut off. Printing starts always with a new line. This may lead to an empty line at the beginning. Especially the first line of a file is reserved for a possible headline. Cartesian complex numbers are printed in braces, with the real and imaginary parts separated by a komma: {Re, Im}. In contrast to MF_write, it is not possible to override the automatic choice of the format used for printing. The number of digits per element is determined by the available space, which depends in turn on the parameters len and linewidth.
Error handling | if len exceeds the maximum number of entries possible for the linewidth chosen, an error message "Cannot use requested format (too many entries per line)!" is generated; in this case, the program truncates the rows at the maximum number of columns possible.
See also | MF_cprint, chapter 14

M_free
Function | de-allocate a matrix
Syntax C/C++ | #include <MFstd.h> void M_free( void **M );
Pascal/Delphi | uses MFstd; procedure M_free( M:Pointer );
Description | The matrix M is freed (i.e. de-allocated). M_free should be used only for the de-allocation of matrices which have previously be allocated by one of the functions of the MF_matrix or MF_matrix0 family. To free several matrices simultaneously, use M_nfree (C/C++ only). To free all allocated vectors and matrices simultaneously, call V_freeAll.
Error handling | Trying to free a matrix that has already been freed, or that has never been allocated memory, leads to a warning message "Cannot free non-existent vector". Program execution is continued without freeing anything in this case.
See also | M_nfree, V_freeAll, MF_matrix, MF_matrix0

M_FtoD | M_FtoE | M_CFtoCD | M_CFtoCE
M_DtoF | M_DtoE | M_CDtoCF | M_CDtoCE
M_EtoF | M_EtoD | M_CEtoCF | M_CEtoCD
Function | Data type interconversions.
Syntax C/C++ | #include <MDstd.h> (always include the <M..std.h> file of the destination data-type!) void M_FtoD( dMatrix MY, fMatrix MX, unsigned ht, unsigned len ); (similarly all other functions of this family)
Pascal/Delphi | uses MDstd; (always include the unit of the destination data-type!) procedure M_FtoD( MY:dMatrix; MX:fMatrix; ht, len:UInt ); (similarly all other functions of this family)
Description | Each element of MX is converted from the data type specified for MX to the data type specified for MY and stored in MY.
Error handling | OVERFLOW errors may occur in the course of the "down-conversions" (e.g., M_EtoF); by default, the extreme value possible for the destination data type is stored in MY with the correct sign.
See also | chapter 4

VF_getLinfitNeglect | VD_getLinfitNeglect | VE_getLinfitNeglect
Function | retrieve the current significance threshold for data fitting to linear models
Syntax C/C++ | #include <MFstd.h> float VF_getLinfitNeglect( void );
Pascal/Delphi | uses MFstd; function VF_getLinfitNeglect:Single;
Description | Internally, the linear-fitting functions like VF_linfit employ a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
Return value | current significance threshold for linear fitting
See also | VF_linfit, VF_multiLinfit, chapter 13.2

VF_getNonlinfitOptions | VD_getNonlinfitOptions | VE_getNonlinfitOptions
Function | retrieve current set of options for nonlinear fitting
Syntax C/C++ | #include <MFstd.h> void VF_getNonlinfitOptions( VF_NONLINFITOPTIONS *Options );
Pascal/Delphi | uses MFstd; procedure VF_getNonlinfitOptions( var Options: VF_NONLINFITOPTIONS );
Description | The nonlinear fitting routines like VF_nonlinfit offer the user a lot of different options, packed into a structure VF_NONLINFITOPTIONS (VD_NONLINFITOPTIONS and VE_NONLINFITOPTIONS for the higher accuracy data-types). These options may be set by the function V_setNonlinfitOptions. To retrieve current settings, use V_getNonlinfitOptions.
See also | chapter 13.3

MF_Hanning | MD_Hanning | ME_Hanning
Function | two-dimensional Hanning window for spatial frequency analysis
Syntax C/C++ | #include <MFstd.h> void MF_Hanning( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Hanning( MA:fMatrix; ht, len:UInt );
Description | MAi,j = 0.25 * (1 - cos( 2 p i / (ht-1) )) * (1 - cos( 2 p j / (len-1) ))
See also | MF_Parzen, MF_Welch, MF_spectrum

MCF_hermconj | MCD_hermconj | MCE_hermconj
Function | Hermitian conjugate of a matrix
Syntax C/C++ | #include <MCFstd.h> void MCF_hermconj( cfMatrix MTr, cfMatrix MA, unsigned htTr, unsigned lenTr );
Pascal/Delphi | uses MCFstd; procedure MCF_hermconj( MTr, MA:cfMatrix; htTr, lenTr:UInt );
Description | The Hermitian conjugate of a complex matrix is defined as the complex conjugate of its transpose: MTri,j = MAj,i* The dimensions fed into this function, htTr and lenTr, refer to the transposed matrix rather than to the input matrix.
See also | MCF_transpose, MCF_conj, chapter 5

MCF_HmulM | MCD_HmulM | MCE_HmulM
Function | multiply the hermitian conjugate of one matrix by another matrix
Syntax C/C++ | #include <MCFstd.h> void MCF_HmulM( cfMatrix MC, cfMatrix MA, cfMatrix MB, unsigned htA, unsigned lenA, unsigned lenB );
Pascal/Delphi | uses MCFstd; procedure MCF_HmulM( MC, MA, MB:cfMatrix; htA, lenA, lenB:UInt );
Description | MC = MAT* * MB htA, lenA, and lenB must be specified; the other dimensions are implicitly given as: htB = htA, lenC = lenB, htC = lenA. htA and lenA refer to the original, un-transposed input matrix.
See also | MCF_hermconj, MCF_mulMH, MF_TmulM, chapter 9

MF_inv | MD_inv | ME_inv
MCF_inv | MCD_inv | MCE_inv
Function | matrix inversion
Syntax C/C++ | #include <MFstd.h> int MF_inv( fMatrix MInv, fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_inv( MInv, MA:fMatrix; len:UInt ):IntBool;
Description | The inverse of the matrix MA is stored in MInv. If MA is non-invertible, the function fails with an error message and returns TRUE (1). Internally, inversion is accomplished via LU decomposition. In order to prevent the function from failing, you can define a minimum pivot for the decomposition, using MF_LUDsetEdit. In that case, any matrix is made invertible, and MF_inv returns always FALSE (0). Only a call to MF_LUDresult will tell you if editing has actually been necessary to avoid a singularity. If such a result is still useful, shall depend on your specific application.
Return value | FALSE (0), if no error occurred, otherwise TRUE (non-zero).
See also | chapter 10

MF_LequU | MD_LequU | ME_LequU
MCF_LequU | MCD_LequU | MCE_LequU
Function | copy upper-diagonal elements into lower-diagonal by index-reflection, so as to get a symmetric matrix
Syntax C/C++ | #include <MFstd.h> void MF_LequU( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_LequU( MA:fMatrix; len:UInt );
Description | MAi,j = MAj,i, i > j
See also | MF_UequL, chapter 3

MF_lincomb | MD_lincomb | ME_lincomb
MCF_lincomb | MCD_lincomb | MCE_lincomb
Function | linear combination of two matrices
Syntax C/C++ | #include <MFstd.h> void MF_lincomb( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len, float CA, float CB );
Pascal/Delphi | uses MFstd; procedure MF_lincomb( MC, MA, MB:fMatrix; ht, len:UInt; CA, CB:Single );
Description | MC = CA * MA + CB * MB
See also | MF_Rows_lincomb, chapter 9

VF_linfit | VD_linfit | VE_linfit
VF_linfitwW | VD_linfitwW | VE_linfitwW
Function | Data-fitting to models y=f(x) linear in the parameters
Syntax C/C++ | #include <MFstd.h> void VF_linfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, ui sizex, void (*funcs)(fVector BasFuncs, float x, unsigned nfuncs)); void VF_linfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fVector InvVar, ui sizex, void (*funcs)(fVector BasFuncs, float x, unsigned nfuncs));
Pascal/Delphi | uses MFstd; procedure VF_linfit( A:fVector; AStatus:iVector; npars:UInt; X, Y:fVector; sizex:UInt; funcs:Pointer ); procedure VF_linfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; npars:UInt; X, Y, InvVar:fVector; sizex:UInt; funcs:Pointer );
Description | The input data X, Y (and InvVar) are used to evaluate the parameters ai of a general linear function, y = a0f0(x) + a1f1(x) + a2f2(x)... The parameters ai are returned in the vector A. Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
X, Y, InvVar | vectors of size sizex, holding the input data
funcs | user-defined model function
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide the vector AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling VF_linfit. npars denotes the total number of parameters in A (not only the free parameters!). The model function funcs must calculate the individual fi(x) for any argument x and store the fi(x) in a vector BasFuncs of size npars. In C/C++, it has to be defined as void MyFunc( fVector BasFuncs, float x, unsigned nfuncs) { BasFuncs[0] = f0( x ); BasFuncs[1] = f1( x); . . . } and shall be passed to VF_linfit by calling VF_linfit( A, AStatus, npars, X, Y, sizex, MyFunc ); In Pascal/Delphi, the model function has to be defined as procedure MyFunc( BasFuncs:fVector; x:Single; nfuncs:UInt ); begin VF_Pelement( BasFuncs, 0 )^ := f0( x ); VF_Pelement( BasFuncs, 1 )^ := f1( x ); . . . end; and shall be passed to VF_linfit by calling VF_linfit( A, AStatus, npars, X, Y, sizex, @MyFunc ); Note the address-of operator in front of "MyFunc.". In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}. The functions f0( x ) etc. must not contain the parameters ai. In the weighted variant, VF_linfitwW, the vector InvVar has to contain the inverse of the variances of the individual X-Y data points, and the matrix Covar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ). Internally, VF_linfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
See also | MF_linfit, VF_nonlinfit, chapter 13, FITDEMO*.*

MF_linfit | MD_linfit | ME_linfit
MF_linfitwW | MD_linfitwW | ME_linfitwW
Function | Data-fitting to models z=f(x, y) linear in the parameters
Syntax C/C++ | #include <MFstd.h> void MF_linfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix MZ, 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 MZ, fMatrix MInvVar, unsigned htZ, unsigned lenZ, void (*funcs)(fVector BasFuncs, float x, float y, unsigned nfuncs));
Pascal/Delphi | uses MFstd; procedure MF_linfit( A:fVector; AStatus:iVector; npars:UInt; X, Y:fVector; MZ:fMatrix; htZ, lenZ:UInt; funcs:Pointer ); procedure MF_linfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; npars:UInt; X, Y:fVector; MZ, MInvVar:fMatrix; htZ, lenZ:UInt; funcs:Pointer );
Description | The input data X, Y, MZ (and MInvVar) are used to evaluate the parameters ai of a general linear function, z = a0f0(x, y) + a1f1(x, y) + a2f2(x, y)... The parameters ai are returned in the vector A. Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
X, Y | vectors of size lenZ and htZ, respectively, spanning the x-y coordinate system of the matrix MZ
MZ, MInvVar | matrices of dimensions [htZ, lenZ], holding the input data and, in the weighted variant, the inverse of their variances
funcs | user-defined model function
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide the vector AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling MF_linfit. npars denotes the total number of parameters in A (not only the free parameters!). You must provide a model function "funcs" which, for any pair of arguments x, y, must calculate the individual fi(x, y) and store them in a vector BasFuncs of size npars. In C/C++, it has to be defined as void MyFunc( fVector BasFuncs, float x, float y, unsigned nfuncs); { BasFuncs[0] = f0( x, y ); BasFuncs[1] = f1( x, y); . . . } and shall be passed to MF_linfit by calling MF_linfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, MyFunc ); In Pascal/Delphi, the model function has to be defined as procedure MyFunc( BasFuncs:fVector; x, y:Single; nfuncs:UInt ); begin VF_Pelement( BasFuncs, 0 )^ := f0( x, y ); VF_Pelement( BasFuncs, 1 )^ := f1( x, y ); . . . end; and shall be passed to MF_linfit by calling MF_linfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, @MyFunc ); Note the address-of operator in front of "MyFunc.". In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}. The functions f0( x, y ) etc. must not contain the parameters ai. In the weighted variant, MF_linfitwW, the matirx MInvVar has to contain the inverse of the variances of the individual X-Y-Z data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ). Internally, MF_linfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
See also | VF_linfit, MF_nonlinfit, chapter 13, FITDEMO*.*

MF_LUdecompose | MD_LUdecompose | ME_LUdecompose
MCF_LUdecompose | MCD_LUdecompose | MCE_LUdecompose
Function | LU decomposition
Syntax C/C++ | #include <MFstd.h> int MF_LUdecompose( fMatrix MLU, uiVector Ind, fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MF_LUdecompose( MLU:fMatrix; Ind:uVector; MA:fMatrix; len:UInt ):Integer;
Description | MA is decomposed into a product MA = L * U, where L is lower-triangular with the diagonal elements equal to 1, and U is upper-triangular. As the combined number of non-trivial elements of L and U just fit into a matrix of the same dimensions as MA, the result is stored in a single matrix MLU rather than in to distinct matrices L and U. Actually, it is not the "true" matrices L and U which are combined into MLU, but rather a row-wise permutation, whose indices are output in the vector Ind. The return value indicates if the number of permuations was even (+1) or uneven (-1). MA may or may not be overwritten by MLU. To check if MF_LUdecompose was successful, call MF_LUDresult, whose return value will be FALSE (0), if the MA could be decomposed, and TRUE (1) for singular MA. There are applications where it makes sense to make near-singular matrices decomposable by "pivot editing": If, in the partial pivoting process employed in the decomposition and inversion, no diagonal element larger than the threshold is available, the scaling of the matrix is done with the threshold value rather than with the tiny diagonal element. That way, divisions by (near-)zero are avoided. This pivot editing can be chosen through a call to MF_LUDsetEdit. By default, pivot editing is switched off. Please note that the present implementation of this function does not employ the fastest possible algorithm. In order to avoid excessive accumulation of round-off error, all dot products are internally summed up in double or extended precision, thus precluding the use of the faster SIMD instructions.
Error handling | In the case of a singular matrix, MLU will be undefined, and an internal flag is set, but no error message is generated. To check if an error occurred, you must call MF_LUDresult.
Return value | +1 or -1, indicating even or uneven number of row permutations
See also | chapter 10

MF_LUdet | MD_LUdet | ME_LUdet
MCF_LUdet | MCD_LUdet | MCE_LUdet
Function | determinant of an LU decomposed matrix
Syntax C/C++ | #include <MFstd.h> float MF_LUdet( fMatrix MLU, unsigned len, int permut );
Pascal/Delphi | uses MFstd; function MF_LUdet( MLU:fMatrix; len:UInt; permut:Integer ): Single;
Description | MF_LUdet calculates the determinant of matrix already decomposed into LU form, and return it as a scalar. The argument permut must be +1 or -1, as given by the return value of MF_LUdecompose
Return value | determinant
See also | MF_det, chapter 10

MF_LUDgetEdit | MD_LUDgetEdit | ME_LUDgetEdit
MCF_LUDgetEdit | MCD_LUDgetEdit | MCE_LUDgetEdit
Function | retrieve pivot-editing threshold for LU decomposition
Syntax C/C++ | #include <MFstd.h> float MF_LUDgetEdit( void );
Pascal/Delphi | uses MFstd; function MF_LUDgetEdit: Single;
Description | retrieve the current pivot-editing threshold for MF_LUdecompose, MF_inv, and MF_solve. It can be modified using MF_LUDsetEdit.
See also | chapter 10

MF_LUDresult | MD_LUDresult | ME_LUDresult
MCF_LUDresult | MCD_LUDresult | MCE_LUDresult
Function | check if the last operation utilizing LU decomposition worked error-free
Syntax C/C++ | #include <MFstd.h> int MF_LUDresult( void );
Pascal/Delphi | uses MFstd; function MF_LUDresult: IntBool;
Description | After a call to MF_LUdecompose or any of the functions internally relying on LU decomposition (like MF_inv, MF_solve), the result should be checked by MF_LUDresult. If LU decomposition was successful, MF_LUDresult returns FALSE (0); if MA was (nearly) singular, TRUE (1) is returned.
Return value | see above
See also | chapter 10

MF_LUDsetEdit | MD_LUDsetEdit | ME_LUDsetEdit
MCF_LUDsetEdit | MCD_LUDsetEdit | MCE_LUDsetEdit
Function | set pivot-editing threshold for LU decomposition
Syntax C/C++ | #include <MFstd.h> void MF_LUDsetEdit( float Thresh );
Pascal/Delphi | uses MFstd; procedure MF_LUDsetEdit( Thresh:Single );
Description | set the pivot-editing threshold for MF_LUdecompose, MF_inv, and MF_solve. To read the current threshold, use MF_LUDgetEdit
See also | chapter 10

MF_LUimprove | MD_LUimprove | ME_LUimprove
MCF_LUimprove | MCD_LUimprove | MCE_LUimprove
Function | iterative improvement of the solution of a linear system solved by LU decomposition
Syntax C/C++ | #include <MFstd.h> void MF_LUimprove( fVector X, fVector B, fMatrix MA, fMatrix MLU, uiVector Ind, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_LUimprove( X, B:fVector; MA, MLU:fMatrix; Ind:uVector; len:UInt );
Description | Especially for large matrices, accumulated round-off error in LU decomposition may become quite noticable. This round-off error will translate into inaccurate results of MF_LUsolve. If the input matrix was not overwritten by the out put matrix in the initial call to MF_LUdecompose, you may call MF_LUimprove after MF_LUsolve to improve the accuracy by iteration. MF_LUimprove needs the output vector X of MF_LUsolve, the right-hand-side vector B of the linear system, and both the original matrix MA and its raw LU-decomposed form MLU along with its permutation indices, Ind, as arguments.
See also | chapter 10

MF_LUinv | MD_LUinv | ME_LUinv
MCF_LUinv | MCD_LUinv | MCE_LUinv
Function | invert a matrix already decomposed into LU form
Syntax C/C++ | #include <MFstd.h> void MF_LUinv( fMatrix MInv, fMatrix MLU, uiVector Ind, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_LUinv( MInv, MLU:fMatrix; Ind:uVector; len:UInt );
Description | MF_LUinv inverts a matrix already decomposed into LU form. Along with the matrix MLU, its permutation indices are needed in the vector Ind as output by MF_LUdecompose
See also | chapter 10

MF_LUsolve | MD_LUsolve | ME_LUsolve
MCF_LUsolve | MCD_LUsolve | MCE_LUsolve
Function | solve a linear system MA * X = B, where MA has already been decomposed into LU form
Syntax C/C++ | #include <MFstd.h> void MF_LUsolve( fVector X, fMatrix MLU, fVector B, uiVector Ind, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_LUsolve( X:fVector; MLU:fMatrix; B:fVector; Ind:uVector; len:UInt );
Description | The linear system MA * X = B is solved for the vector X. Instead of MA itself, this function expects the LU decomposed form of MA as the input matrix MLU, along with its row-permutation indices in the vector Ind as output by MF_LUdecompose. If the original matrix MA is still available, it is recommended to "fine-polish" the result by calling MF_LUimprove. In comparison to the LU decomposition and back-substitution already performed, this iterative improvement takes very little time, but it can lead to an appreaciable improvement of the solution and often even save solutions which otherwise would be ruined by round-off error.
See also | chapter 10

MF_matrix | MD_matrix | ME_matrix
MCF_matrix | MCD_matrix | MCE_matrix
Function | Memory allocation for a matrix
Syntax C/C++ | #include <MFstd.h> fMatrix MF_matrix( unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; function MF_matrix( ht, len:UInt ): fMatrix;
Description | Based on memory model and environment, the most appropriate allocation procedure is chosen by these functions. Failure to allocate memory always leads to an error message and a subsequent program abort (similar to the error handling of the "new" operator). To release the memory thus allocated, M_free, M_nfree, or V_freeAll should be used (M_nfree only in C/C++). Note: the declaration of a matrix (e.g., as fMatrix) reserves only a name, but no memory! See chapter 4.1 if you are interested in details of the implementation.
Error handling | If there is not enough memory available, or if size is zero, an error message "Not enough memory" is displayed and the program aborted. 16-bit models: If more than 64 kB of memory are requested, an error message "Vector > 64 kB not possible" is displayed and the program aborted (except in the model HUGE). If any of the two matrix dimensions exceeds the 64 kB limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted, even in the model HUGE. 32-bit: If more than 4 GB of memory are requested, an error message "Vector > 4 GB not possible" is displayed and the program aborted. If already a single matrix dimensions exceeds this limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted.
Return value | C/C++: Pointer to the array of row pointers Pascal/Delphi: Pointer to the allocated memory
See also | MF_matrix0, VF_vector, chapter 2

MF_matrix0 | MD_matrix0 | ME_matrix0
MCF_matrix0 | MCD_matrix0 | MCE_matrix0
Function | allocate memory for a matrix and initialize all elements with 0
Syntax C/C++ | #include <MFstd.h> fMatrix MF_matrix0( unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; function MF_matrix0( ht, len:UInt ): fMatrix;
Description | The functions of this family are almost identical to those of the MF_matrix family; in addition to allocating memory, they initialize all elements with 0. (Calls to MF_matrix and MF_matrix0 may be mixed; they and the vector allocation functions, VF_vector etc. use the same tables to keep track of the handles and pointers). For further information, see MF_matrix.
Error handling | If there is not enough memory available, or if size is zero, an error message "Not enough memory" is displayed and the program aborted. 16-bit models: If more than 64 kB of memory are requested, an error message "Vector > 64 kB not possible" is displayed and the program aborted (except in the model HUGE). If any of the two matrix dimensions exceeds the 64 kB limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted, even in the model HUGE. 32-bit: If more than 4 GB of memory are requested, an error message "Vector > 4 GB not possible" is displayed and the program aborted. If already a single matrix dimensions exceeds this limit, an error message "Invalid matrix dimension(s)" is displayed and the program aborted.
Return value | C/C++: Pointer to the array of row pointers Pascal/Delphi: Pointer to the allocated memory
See also | MF_matrix, VF_vector0, chapter 2

MF_MatrixTo2DArray | MD_MatrixTo2DArray | ME_MatrixTo2DArray
MCF_MatrixTo2DArray | MCD_MatrixTo2DArray | MCE_MatrixTo2DArray
Function | convert OptiVec matrix into 2D-array of Delphi 4 or higher
Syntax C/C++ | N.A.
Pascal/Delphi | uses VecLib, MFstd; type fArray = array of Single; type f2DArray = array of fArray; procedure MF_MatrixTo2DArray( DelphiArr:f2DArray; MF:fMatrix; ht,len:UInt);
Description | This function is necessary only for Delphi 4 or higher. (Previous versions of Borland Pascal/Delphi did not support dynamically allocated matrices.) It converts OptiVec matrices into two-dimensional Delphi arrays. Note that, unlike static Pascal/Delphi matrices, the dynamic matrices of Delphi 4+ cannot directly be passed to OptiVec functions, but have to be converted first by calling MF_2DArrayToMatrix. If you ever need an OptiVec matrix back into Delphi format, this is done by the present function.
See also | MF_2DArrayToMatrix, chapter 1.4

MF_mulC | MD_mulC | ME_mulC
MCF_mulC | MCD_mulC | MCE_mulC
MCF_mulReC | MCD_mulReC | MCE_mulReC
Function | multiply all matrix element by a constant
Syntax C/C++ | #include <MFstd.h> void MF_mulC( fMatrix MB, fMatrix MA, unsigned ht, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_mulC( MB, MA:fMatrix; ht, len:UInt; C:Single );
Description | MBij = MAij + C
See also | MF_mulV, MF_mulM, chapter 9

VF_mulM | VD_mulM | VE_mulM
Function | multiply a row vector by a matrix
Syntax C/C++ | #include <MFstd.h> void VF_mulM( fVector Y, fVector X, fMatrix MA, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; procedure VF_mulM( Y, X:fVector; MA:fMatrix; htA, lenA:UInt );
Description | Y = X * MA; the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = htA, sizY = lenA.
See also | MF_mulV, MF_mulM, chapter 9

MF_mulM | MD_mulM | ME_mulM
MCF_mulM | MCD_mulM | MCE_mulM
Function | matrix multiplication
Syntax C/C++ | #include <MFstd.h> void MF_mulM( fMatrix MC, fMatrix MA, fMatrix MB, unsigned htA, unsigned lenA, unsigned lenB );
Pascal/Delphi | uses MFstd; procedure MF_mulM( MC, MA, MB:fMatrix; htA, lenA, lenB:UInt );
Description | MC = MA * MB htA, lenA, and lenB must be specified; the other dimensions are implicitly given as: htB = lenA, lenC = lenB, htC = htA.
See also | MF_mulMT, MF_TmulM, VF_mulM, chapter 9

MFdia_mulM | MDdia_mulM | MEdia_mulM
MCFdia_mulM | MCDdia_mulM | MCEdia_mulM
Function | multiplication of a diagonal matrix and a general matrix
Syntax C/C++ | #include <MFstd.h> void MFdia_mulM( fMatrix MC, fVector MADia, fMatrix MB, unsigned lenA, unsigned lenB );
Pascal/Delphi | uses MFstd; procedure MFdia_mulM( MC:fMatrix; MADia: fVector; MB:fMatrix; lenA, lenB:UInt );
Description | MC = MADia * MB The vector MAdia represents the diagonal matrix MA. (A matrix is called diagonal, it it has non-zero elements only on the diagonal). lenA, and lenB must be specified; htB is equal to lenA.
See also | MFdia_mulMT, chapter 9

MF_mulMdia | MD_mulMdia | ME_mulMdia
MCF_mulMdia | MCD_mulMdia | MCE_mulMdia
Function | multiply a general matrix by a diagonal matrix
Syntax C/C++ | #include <MFstd.h> void MF_mulMdia( fMatrix MC, fMatrix MA, fVector MBDia, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; procedure MF_mulMdia( MC, MA:fMatrix; MBDia:fVector; htA, lenA:UInt );
Description | MC = MA * MBDia. htA and lenA must be specified; sizB = lenA.
See also | MFdia_mulM, MF_TmulMdia, chapter 9

MCF_mulMH | MCD_mulMH | MCE_mulMH
Function | multiply one complex matrix by the hermitian conjugate of another
Syntax C/C++ | #include <MCFstd.h> void MCF_mulMH( cfMatrix MC, cfMatrix MA, cfMatrix MB, unsigned htA, unsigned lenA, unsigned htB );
Pascal/Delphi | uses MCFstd; procedure MCF_mulMH( MC, MA, MB:cfMatrix; htA, lenA, htB:UInt );
Description | MC = MA * MBT *. htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = lenA, lenC = htB, htC = htA.
See also | MCF_hermconj, | MF_mulMT, MCF_HmulM, chapter 9

MF_mulMT | MD_mulMT | ME_mulMT
MCF_mulMT | MCD_mulMT | MCE_mulMT
Function | multiply one matrix by the transpose of another
Syntax C/C++ | #include <MFstd.h> void MF_mulMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned htA, unsigned lenA, unsigned htB );
Pascal/Delphi | uses MFstd; procedure MF_mulMT( MC, MA, MB:fMatrix; htA, lenA, htB:UInt );
Description | MC = MA * MBT. htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = lenA, lenC = htB, htC = htA.
See also | MF_mulM, MF_TmulM, VF_mulMT, chapter 9

MFdia_mulMT | MDdia_mulMT | MEdia_mulMT
MCFdia_mulMT | MCDdia_mulMT | MCEdia_mulMT
Function | multiply a diagonal matrix by the transpose of a general matrix
Syntax C/C++ | #include <MFstd.h> void MFdia_mulMT( fMatrix MC, fVector MADia, fMatrix MB, unsigned htB, unsigned lenB );
Pascal/Delphi | uses MFstd; procedure MFdia_mulMT( MC:fMatrix; MADia: fVector; MB:fMatrix; htB, lenB:UInt );
Description | MC = MADia * MBT htB and lenB must be specified; sizA equals lenB.
See also | MFdia_mulM, chapter 9

VF_mulMT | VD_mulMT | VE_mulMT
Function | multiply a row vector by the transpose of a matrix
Syntax C/C++ | #include <MFstd.h> void VF_mulMT( fVector Y, fVector X, fMatrix MA, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; procedure VF_mulMT( Y, X:fVector; MA:fMatrix; htA, lenA:UInt );
Description | Y = X * MAT The dimensions htA and lenA refer to the original (rather than the intermediate transposed) matrix MA; the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = lenA, sizY = htA.
See also | VF_mulM, MF_mulV, chapter 9

VF_multiLinfit | VD_multiLinfit | VE_multiLinfit
VF_multiLinfitwW | VD_multiLinfitwW | VE_multiLinfitwW
Function | fit multiple X-Y data sets to a common model function, linear in its parameters
Syntax C/C++ | #include <MFstd.h> void VF_multiLinfit( fVector A, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments, void (*funcs)(fVector BasFuncs, float x,unsigned nfuncs, unsigned iexperiment) ); void VF_multiLinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments, void (*funcs)(fVector BasFuncs, float x, unsigned nfuncs, unsigned iexperiment) );
Pascal/Delphi | uses MFstd; procedure VF_multiLinfit( A:fVector; AStatus:iVector; nParameters:UInt; ListOfExperiments: PVF_EXPERIMENT; nexperiments:UInt; funcs: Pointer ); procedure VF_multiLinfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; nParameters:UInt; ListOfExperiments:PVF_EXPERIMENT; nexperiments:UInt; funcs:Pointer );
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameters ai of a general linear function, y = a0f0(x) + a1f1(x) + a2f2(x)... The parameters ai are returned in the vector A. Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
ListOfExperiments | input data, see chap. 13.4
nexperiments | number of data sets in ListOfExperiments
funcs | user-defined model function
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling VF_multiLinfit. The argument npars denotes the total number of parameters in A (not only the free parameters!). The input data must be combined into sets of the type VF_EXPERIMENT. Assuming you have two sets of X-Y data, contained in the vectors X1, Y1 (and, for VF_multiLinfitwW, InvVar1) of size1 elements, and X2, Y2 (and InvVar2) of size2 elements, you have to construct a list of experiments as in the following example:
Constructing list of experiments in C/C++ | VF_EXPERIMENT ExpList[2]; ExpList[0].X = X1; ExpList[0].Y = Y1; ExpList[0].size = size1; ExpList[1].X = X2; ExpList[1].Y = Y2; ExpList[1].size = size2; /* for the weighted variant, set additionally: */ ExpList[0].InvVar = InvVar1; ExpList[0].WeightOfExperiment = wt1; ExpList[1].InvVar = InvVar2; ExpList[1].WeightOfExperiment = wt2;
Constructing list of experiments in Pascal/Delphi | var ExpList: array[0..1] of VF_EXPERIMENT; begin ... ExpList[0].X := X1; ExpList[0].Y := Y1; ExpList[0].size := size1; ExpList[1].X := X2; ExpList[1].Y := Y2; ExpList[1].size := size2; (* for the weighted variant, set additionally: *) ExpList[0].InvVar := InvVar1; ExpList[0].WeightOfExperiment := wt1; ExpList[1].InvVar := InvVar2; ExpList[1].WeightOfExperiment := wt2; ... end;
Both C/C++ and Pascal/Delphi | You must provide a model function "funcs" which, for any argument x, must calculate the individual basis functions fi(x) and store them in a vector BasFuncs. The model function has to be defined as
Model function for C/C++ | void MyFunc( fVector BasFuncs, float x, unsigned nfuncs, unsigned iexperiment ) { BasFuncs[0] = f0( x ); BasFuncs[1] = f1( x); ... } and shall be passed to VF_multiLinfit by calling VF_multiLinfit( A, AStatus, npars, ExpList, 2, MyFunc );
Model function for Pascal/Delphi | procedure MyFunc( BasFuncs:fVector; x:Single; nfuncs, iexperiment:UInt ); begin VF_Pelement( BasFuncs, 0 )^ := f0( x ); VF_Pelement( BasFuncs, 1 )^ := f1( x ); ... end; This model function shall be passed to VF_multiLinfit by calling VF_multiLinfit( A, AStatus, npars, @ExpList, 2, @MyFunc ); Note the address-of operators in front of "ExpList" (static Pascal array passed to OptiVec function) and "MyFunc." (pointer to the function MyFunc). In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}.
Both C/C++ and Pascal/Delphi | The argument iexperiment with which MyFunc shall be called by VF_multiLinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's Y values might be shifted by a constant C. In this case, A has to contain as many shifts C as there are experiments. In MyFunc, you would have to code this as (in C/C++; you will easily translate this into Pascal/Delphi): if( iexperiment == 0 ) { BasFuncs[2] = 1; BasFuncs[3] = 0; } else {BasFuncs[2] = 0; BasFuncs[3] = 1; } The functions f0( x ) etc. must not contain the parameters ai. In the weighted variant, the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ). Internally, VF_multiLinfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
See also | MF_linfit, VF_nonlinfit, chapter 13, FITDEMO*.*

MF_multiLinfit | MD_multiLinfit | ME_multiLinfit
MF_multiLinfitwW | MD_multiLinfitwW | ME_multiLinfitwW
Function | fit multiple X-Y-Z data sets to a common model function, linear in its parameters
Syntax C/C++ | #include <MFstd.h> void MF_multiLinfit( fVector A, iVector AStatus, unsigned npars, MF_EXPERIMENT *ListOfExperiments, unsigned nexperiments, void (*funcs)(fVector BasFuncs, float x, float y, unsigned nfuncs, unsigned iexperiment) ); void MF_multiLinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, MF_EXPERIMENT *ListOfExperiments, unsigned nexperiments, void (*funcs)(fVector BasFuncs, float x, float y, unsigned nfuncs, unsigned iexperiment) );
Pascal/Delphi | uses MFstd; procedure MF_multiLinfit( A:fVector; AStatus:iVector; nParameters:UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments:UInt; funcs: Pointer ); procedure MF_multiLinfitwW( A:fVector; Covar:fMatrix; AStatus:iVector; nParameters:UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments:UInt; funcs: Pointer );
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameters ai of a general linear function, z = a0f0(x,y) + a1f1(x,y) + a2f2(x,y)... The parameters ai are returned in the vector A. Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
ListOfExperiments | input data, see chap. 13.4
nexperiments | number of data sets in ListOfExperiments
funcs | user-defined model function
Your model function may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). Any fixed parameters must be initialized in A prior to calling MF_multiLinfit. The argument npars denotes the total number of parameters in A (not only the free parameters!). The input data must be combined into sets of the type MF_EXPERIMENT. Let us assume you have two sets of X-Y-Z data, each with the vectors X and Y for the independent variables, the matrix MZ for the z=f(x,y) values and, for MF_multiLinfitwW, the weights of all points in MInvVar. The matrix dimensions are htZ (equal to sizeY) and lenZ (equal to sizeX). Now you have to construct a list of experiments as in the following example:
Constructing list of experiments in C/C++ | MF_EXPERIMENT ExpList[2]; ExpList[0].X = X1; ExpList[0].Y = Y1; ExpList[0].MZ = MZ1; ExpList[0].htZ = htZ1; ExpList[0].lenZ = lenZ1; ExpList[1].X = X1; ExpList[1].Y = Y2; ExpList[1].MZ = MZ2; ExpList[1].htZ = htZ2; ExpList[1].lenZ = lenZ2; /* for the weighted variant, set additionally: */ ExpList[0].MInvVar = MInvVar1; ExpList[0].WeightOfExperiment = wt1; ExpList[1].MInvVar = MInvVar2; ExpList[1].WeightOfExperiment = wt2;
Constructing list of experiments in Pascal/Delphi | var ExpList: array[0..1] of MF_EXPERIMENT; begin ... ExpList[0].X := X1; ExpList[0].Y := Y1; ExpList[0].MZ := MZ1; ExpList[0].htZ := htZ1; ExpList[0].lenZ := lenZ1; ExpList[1].X := X2; ExpList[1].Y := Y2; ExpList[1].MZ := MZ2; ExpList[1].htZ := htZ2; ExpList[1].lenZ := lenZ2; (* for the weighted variant, set additionally: *) ExpList[0].MInvVar := MInvVar1; ExpList[0].WeightOfExperiment := wt1; ExpList[1].MInvVar := MInvVar2; ExpList[1].WeightOfExperiment := wt2; ... end;
Both C/C++ and Pascal/Delphi | You must provide a model function "funcs" which, for any argument x, must calculate the individual basis functions fi(x,y) and store them in a vector BasFuncs. The model function has to be defined as
Model function for C/C++ | void MyFunc( fVector BasFuncs, float x, float y, unsigned nfuncs, unsigned iexperiment ) { BasFuncs[0] = f0( x, y ); BasFuncs[1] = f1( x, y ); ... } and shall be passed to MF_multiLinfit by calling MF_multiLinfit( A, AStatus, npars, ExpList, 2, MyFunc );
Model function for Pascal/Delphi | procedure MyFunc( BasFuncs:fVector; x, y:Single; nfuncs, iexperiment:UInt ); begin VF_Pelement( BasFuncs, 0 )^ := f0( x, y ); VF_Pelement( BasFuncs, 1 )^ := f1( x, y ); ... end; This model function shall be passed to MF_multiLinfit by calling MF_multiLinfit( A, AStatus, npars, @ExpList, 2, @MyFunc ); Note the address-of operators in front of "ExpList" (static Pascal array passed to OptiVec function) and "MyFunc." (pointer to the function MyFunc). In Turbo Pascal, the model function must be compiled with the Force-Far-Calls option {$F+}.
Both C/C++ and Pascal/Delphi | The argument iexperiment with which MyFunc shall be called by MF_multiLinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's MZ values might be shifted by a constant C. In this case, A has to contain as many shifts Ci as there are experiments. In MyFunc, you would have to code this as (in C/C++; you will easily translate this into Pascal/Delphi yourself): if( iexperiment == 0 ) { BasFuncs[2] = 1; BasFuncs[3] = 0; } else {BasFuncs[2] = 0; BasFuncs[3] = 1; } The functions f0( x,y ) etc. must not contain the parameters ai. In the weighted variant, the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ). Internally, MF_multiLinfit employs a Singular Value Decomposition algorithm to obtain a solution even for (near-)singular linear systems. Thereby, coefficients ai whose significance is lower than a threshold, Thresh, are set to 0 instead of infinity. This threshold can be modified by calling VF_setLinfitNeglect. The current threshold can be retrieved by VF_getLinfitNeglect.
See also | MF_linfit, MF_nonlinfit, MF_multiNonlinfit, chapter 13, FITDEMO*.*

VF_multiNonlinfit | VD_multiNonlinfit | VE_multiNonlinfit
VF_multiNonlinfitwW | VD_multiNonlinfitwW | VE_multiNonlinfitwW
Function | fit multiple X-Y data sets to a common model function, possibly non-linear in its parameters
Syntax C/C++ | #include <MFstd.h> float VF_multiNonlinfit( fVector A, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments, void (*modelfunc)(fVector YModel, fVector XModel, ui size, unsigned iexperiment), void (*derivatives)(fVector dYdAi,fVector X, ui size, unsigned ipar, unsigned iexperiment) ); float VF_multiNonlinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, VF_EXPERIMENT *ListOfExperiments, unsigned nexperiments, void (*modelfunc)(fVector YModel, fVector X, ui size, unsigned iexperiment), void (*derivatives)(fVector dYdAi, fVector X, ui size, unsigned ipar, unsigned iexperiment) );
Pascal/Delphi | uses VFmnlfit; function VF_multiNonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; ListOfExperiments: PVF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single; function VF_multiNonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; ListOfExperiments: PVF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single;
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameter array A with npars elements ai of an arbitrary model function y = f(x). Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
ListOfExperiments | input data, see chap. 13.4
nexperiments | number of data sets in ListOfExperiments
modelfunc | user-defined model function
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling VF_multiNonlinfit. The better your initial guess of the parameters, the faster VF_multiNonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!). The input data must be combined into sets of the type VF_EXPERIMENT. Assuming you have two sets of X-Y data, contained in the vectors X1, Y1 (and, for VF_multiLinfitwW, InvVar1) of size1 elements, and X2, Y2 (and InvVar2) of size2 elements, you have to construct a list of experiments as in the following example:
Constructing list of experiments in C/C++ | VF_EXPERIMENT ExpList[2]; ExpList[0].X = X1; ExpList[0].Y = Y1; ExpList[0].size = size1; ExpList[1].X = X2; ExpList[1].Y = Y2; ExpList[1].size = size2; /* for the weighted variant, set additionally: */ ExpList[0].InvVar = InvVar1; ExpList[0].WeightOfExperiment = wt1; ExpList[1].InvVar = InvVar2; ExpList[1].WeightOfExperiment = wt2;
Constructing list of experiments in Pascal/Delphi | var ExpList: array[0..1] of VF_EXPERIMENT; begin ... ExpList[0].X := X1; ExpList[0].Y := Y1; ExpList[0].size := size1; ExpList[1].X := X2; ExpList[1].Y := Y2; ExpList[1].size := size2; /* for the weighted variant, set additionally: */ ExpList[0].InvVar := InvVar1; ExpList[0].WeightOfExperiment := wt1; ExpList[1].InvVar := InvVar2; ExpList[1].WeightOfExperiment := wt2; ... end;
Both C/C++ and Pascal/Delphi | You must provide a model function "modelfunc" which, for a given vector of x-values, must calculate the corresponding "theoretical" y-values. In C/C++, it has to be defined as
Model function for C/C++ | void _cdecl MyFunc( fVector Y, fVector X, ui size, unsigned iexperiment ) { for (ui i=0; i<size; i++ ) Y[i] = f( X[i] ); } f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS). The argument iexperiment with which MyFunc shall be called by VF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's Y values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like: if( iexperiment == 0 ) Y[i] *= A[5]; else Y[i] *= A[6]; In addition to the model function, VF_multiNonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for C/C++ | void _cdecl MyDerivs( fVector dYdAi, fVector X, ui size, unsigned ipar, unsigned iexperiment ) { ui i; switch( ipar ) { case 0: for(i=0; i<size; i++ ) dYdAi[i] = part_derv_of_Y_w_resp_to_A0( X[i] ); break; case 1: for(i=0; i<size; i++ ) dYdAi[i] = part_derv_of_Y_w_resp_to_A1( X[i] ); break; default: /* for all derivatives we don't know: */ VF_multiNonlinfit_autoDeriv( dYdAi, X, size, ipar, iexperiment ); } } Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters. A call to VF_multiNonlinfit will look like: VF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, MyDerivs ); In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_multiNonlinfit with derivaties = NULL: VF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, NULL );
Model function for Pascal/Delphi | In Pascal/Delphi, the model function has to be defined as procedure MyFunc( Y, X:fVector; size, iexperiment:UInt ); var i:UInt; begin for i:=0 to size-1 do VF_Pelement( Y, i )^ := f( VF_element( X, i ) ); end; f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see chapter 13.3). The argument iexperiment with which MyFunc shall be called by VF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's Y values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like: if iexperiment = 0 then VF_Pelement(Y,i)^ := VF_element(Y,i) * VF_element(A,5) else VF_Pelement(Y,i)^ := VF_element(Y,i) * VF_element(A,6); In addition to the model function, VF_multiNonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for Pascal/Delphi | procedure MyDerivs( dYdAi, X:fVector; size, ipar, iexperiment:UInt ); var i:UInt; begin case ipar of 0: begin for i:=0 to size-1 do VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end; 1: begin for i:=0 to size-1 do VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end; else (* for all derivatives we don't know: *) VF_multiNonlinfit_autoDeriv( dYdAi, X, size, ipar, iexperiment ); end; end; Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters. A call to VF_multiNonlinfit will look like: VF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, @MyDerivs ); Note the address-of operator in front of "ExpList", "MyFunc.", and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_multiNonlinfit with derivaties = nil: VF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, nil ); In the weighted variant, VF_multiNonlinfitwW, the vector ExpList[i].InvVar of each experiment has to contain the inverse of the variances of the individual X-Y data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
Both C/C++ and Pascal/Delphi: | For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of VF_multiNonlinfit, described here.
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, VF_nonlinfit and VF_multiNonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run VF_multiNonlinfit and VD_multiNonlinfit in parallel. These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy.
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1
See also | VF_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 |
Function | helper 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/Delphi | uses VFmnlfit; procedure VF_multiNonlinfit_autoDeriv( dYdAi, X:fVector; size, ipar, iex:UInt ); function VF_multiNonlinfit_getChi2: Single; procedure VF_multiNonlinfit_getChi2Detail( Chi2Detail:fVector ); procedure VF_multiNonlinfit_getBestValues( BestValues: fVector ); function VF_multiNonlinfit_getTestDir: Integer; function VF_multiNonlinfit_getTestPar: UInt; function VF_multiNonlinfit_getTestRun: UInt; procedure VF_multiNonlinfit_stop; (identical syntax for the VF_multiNonlinfitwW_... functions)
Description | VF_multiNonlinfit_autoDeriv performs a numerical differentiation of a user-provided y=f(x) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to VF_multiNonlinfit. The model function that is differentiated by VF_multiNonlinfit_autoDeriv is the one passed in the same call to VF_multiNonlinfit (see that function for details!). The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function. VF_multiNonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before VF_multiNonlinfit has had the chance to calculate c2, VF_multiNonlinfit_getChi2 returns -1.0. VF_multiNonlinfit_getChi2Detail fills the user-supplied vector Chi2Detail with the individual figures-of-merit (c2iex or, for robust fits, |ciex|) for all experiments. The sum over these individual c2iex or |ciex| values is the best c2 (or |c|) obtained so far, as returned by VF_multiNonlinfit_getChi2. VF_multiNonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest. VF_multiNonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions). VF_multiNonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation. VF_multiNonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first. VF_multiNonlinfit_stop makes VF_multiNonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data.
See also | chapter 13

MF_multiNonlinfit | MD_multiNonlinfit | ME_multiNonlinfit
MF_multiNonlinfitwW | MD_multiNonlinfitwW | ME_multiNonlinfitwW
Function | fit multiple X-Y-Z data sets to a common model function, possibly non-linear in its parameters
Syntax C/C++ | #include <MFstd.h> float MF_multiNonlinfit( fVector A, iVector AStatus, unsigned npars, MF_EXPERIMENT _VFAR *ListOfExperiments, unsigned nexperiments, void (*modelfunc)(fMatrix MZModel, 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 MZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned iexperiment ), void (*derivatives)(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar, unsigned iexperiment) );
Pascal/Delphi | uses MFmnlfit; function MF_multiNonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single; function MF_multiNonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; ListOfExperiments: PMF_EXPERIMENT; nexperiments: UInt; ModelFunc, Derivatives: Pointer ): Single;
Description | The input data, contained in ListOfExperiments, are used to evaluate the parameter array A with npars elements ai of an arbitrary model function z = f(x, y). Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
ListOfExperiments | input data, see chap. 13.4
nexperiments | number of data sets in ListOfExperiments
modelfunc | user-defined model function
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling MF_multiNonlinfit. The better your initial guess of the parameters, the faster MF_multiNonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!). The input data must be combined into sets of the type MF_EXPERIMENT. Let us assume you have two sets of X-Y-Z data, each with the vectors X and Y for the independent variables, the matrix MZ for the z=f(x,y) values and, for MF_multiLinfitwW, the weights of all points in MInvVar. The matrix dimensions are htZ (equal to sizeY) and lenZ (equal to sizeX). Now you have to construct a list of experiments as in the following example:
Constructing list of experiments in C/C++ | MF_EXPERIMENT ExpList[2]; ExpList[0].X = X1; ExpList[0].Y = Y1; ExpList[0].MZ = MZ1; ExpList[0].htZ = htZ1; ExpList[0].lenZ = lenZ1; ExpList[1].X = X1; ExpList[1].Y = Y2; ExpList[1].MZ = MZ2; ExpList[1].htZ = htZ2; ExpList[1].lenZ = lenZ2; /* for the weighted variant, set additionally: */ ExpList[0].MInvVar = MInvVar1; ExpList[0].WeightOfExperiment = wt1; ExpList[1].MInvVar = MInvVar2; ExpList[1].WeightOfExperiment = wt2;
Constructing list of experiments in Pascal/Delphi | var ExpList: array[0..1] of MF_EXPERIMENT; begin ... ExpList[0].X := X1; ExpList[0].Y := Y1; ExpList[0].MZ := MZ1; ExpList[0].htZ := htZ1; ExpList[0].lenZ := lenZ1; ExpList[1].X := X2; ExpList[1].Y := Y2; ExpList[1].MZ := MZ2; ExpList[1].htZ := htZ2; ExpList[1].lenZ := lenZ2; /* for the weighted variant, set additionally: */ ExpList[0].MInvVar := MInvVar1; ExpList[0].WeightOfExperiment := wt1; ExpList[1].MInvVar := MInvVar2; ExpList[1].WeightOfExperiment := wt2; ... end;
Both C/C++ and Pascal/Delphi | You must provide a model function "modelfunc" which, for a given pair of X, Y vectors, must calculate the corresponding "theoretical" z-values. In C/C++, it has to be defined as
Model function for C/C++ | void _cdecl MyFunc( fMatrix MZ, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned iexperiment ) { for (ui i=0; i<htZ; i++ ) for (ui j=0; j<lenZ; j++ ) MZ[i][j] = f( X[j], Y[i] ); } f( X[j], Y[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS). The argument iexperiment with which MyFunc shall be called by MF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's MZ values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like: if( iexperiment == 0 ) MZ[i][j] *= A[5]; else MZ[i][j] *= A[6]; In addition to the model function, MF_multiNonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for C/C++ | void _cdecl MyDerivs( fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar, unsigned iexperiment ) { ui i; switch( ipar ) { case 0: for(i=0; i<htZ; i++ ) for( j=0; j<lenZ; j++ ) dZdAi[i][j] = part_derv_MZ_w_resp_to_A0( X[j], Y[i] ); break; case 1: for(i=0; i<htZ; i++ ) for( j=0; j<lenZ; j++ ) dZdAi[i][j] = part_derv_MZ_w_resp_to_A1( X[j], Y[i] ); break; default: /* for all derivatives we don't know: */ MF_multiNonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar, iexperiment ); } } Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters. A call to MF_multiNonlinfit will look like: MF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, MyDerivs ); In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_multiNonlinfit with derivaties = NULL: MF_multiNonlinfit( A, AStatus, npars, ExpList, 2, MyFunc, NULL );
Model function for Pascal/Delphi | In Pascal/Delphi, the model function has to be defined as procedure MyFunc( MZ:fMatrix; htZ, lenZ:UInt; X, Y:fVector; iexperiment:UInt ); var i, j:UInt; begin for i:=0 to htZ-1 do for j:=0 to lenZ-1 do MF_Pelement( MZ, htZ, lenZ, i, j )^ := f( VF_element( X, j ), VF_element( Y, i ) ); end; f( Xj, Yi ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS). The argument iexperiment with which MyFunc shall be called by MF_multiNonlinfit allows to distinguish between parameters that are common to all experiments and others that belong to individual experiments. For example, each experiment's MZ values might be scaled by an individual constant C. In this case, A has to contain as many scales C as there are experiments. In MyFunc, you would have to code this as something like: if iexperiment = 0 then MF_Pelement(MZ, htZ, lenZ, i, j)^ := MF_element(MZ, htZ, lenZ, i, j) * VF_element(A,5) else MF_Pelement(MZ, htZ, lenZ, i, j)^ := MF_element(MZ, htZ, lenZ, i, j) * VF_element(A,6); In addition to the model function, MF_multiNonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_multiNonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for Pascal/Delphi | procedure MyDerivs( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar, iexperiment:UInt ); var i, j:UInt; begin case ipar of 0: begin for i:=0 to htZ-1 do for j:=0 to lenZ-1 do MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A0(VF_element( X, j ), VF_element( Y, i )); end; 1: begin for i:=0 to htZ-1 do for j:=0 to lenZ-1 do MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A1(VF_element( X, j ), VF_element( Y, i )); end; else (* for all derivatives we don't know: *) MF_multiNonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar ); end; end; Again, the argument iexperiment allows you to treat "private" parameters of the individual experiments differently from the shared parameters. A call to MF_multiNonlinfit will look like: MF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, @MyDerivs ); Note the address-of operator in front of "ExpList", "MyFunc.", and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_multiNonlinfit with derivaties = nil: MF_multiNonlinfit( A, AStatus, npars, @ExpList, 2, @MyFunc, nil ); In the weighted variant, MF_multiNonlinfitwW, the matrix ExpList[i].MInvVar of each experiment has to contain the inverse of the variances of the individual X-Y-Z data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
Both C/C++ and Pascal/Delphi: | For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of MF_multiNonlinfit, described here.
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, MF_multiNonlinfit and MF_multiNonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run MF_multiNonlinfit and MD_multiNonlinfit in parallel. These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy.
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1
See also | VF_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 |
Function | helper 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/Delphi | uses MFmnlfit; procedure MF_multiNonlinfit_autoDeriv( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar, iex: UInt ); function MF_multiNonlinfit_getChi2: Single; procedure MF_multiNonlinfit_getChi2Detail( Chi2Detail:fVector ); procedure MF_multiNonlinfit_getBestValues( BestValues: fVector ); function MF_multiNonlinfit_getTestDir: Integer; function MF_multiNonlinfit_getTestPar: UInt; function MF_multiNonlinfit_getTestRun: UInt; procedure MF_multiNonlinfit_stop; (identical syntax for the MF_multiNonlinfitwW_... functions)
Description | MF_multiNonlinfit_autoDeriv performs a numerical differentiation of a user-provided z=f(x,y) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to MF_multiNonlinfit. The model function that is differentiated by MF_multiNonlinfit_autoDeriv is the one passed in the same call to MF_multiNonlinfit (see that function for details!). The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function. MF_multiNonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before MF_multiNonlinfit has had the chance to calculate c2, MF_multiNonlinfit_getChi2 returns -1.0. MF_multiNonlinfit_getChi2Detail fills the user-supplied vector Chi2Detail with the individual figures-of-merit (c2iex or, for robust fits, |ciex|) for all experiments. The sum over these individual c2iex or |ciex| values is the best c2 (or |c|) obtained so far, as returned by MF_multiNonlinfit_getChi2. MF_multiNonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest. MF_multiNonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions). MF_multiNonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation. MF_multiNonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first. MF_multiNonlinfit_stop makes MF_multiNonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data.
See also | chapter 13

MF_mulV | MD_mulV | ME_mulV
MCF_mulV | MCD_mulV | MCE_mulV
Function | multiply a matrix by a column vector
Syntax C/C++ | #include <MFstd.h> void MF_mulV( fVector Y, fMatrix MA, fVector X, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; procedure MF_mulV( Y:fVector; MA:fMatrix; X:fVector; htA, lenA:UInt );
Description | Y = MA * X the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = lenA, sizY = htA.
See also | MF_TmulV, VF_mulM, chapter 9

MF_neg | MD_neg | ME_neg
MCF_neg | MCD_neg | MCE_neg
Function | negation
Syntax C/C++ | #include <MFstd.h> void MF_neg( fMatrix MB, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_neg( MB, MA:fMatrix; ht, len:UInt );
Description | MBi,j = -MAi,j
See also | MCF_conj, chapter 3

M_nfree
Function | de-allocate a certain number of matrices (C/C++ only)
Syntax C/C++ | #include <MFstd.h> void M_nfree( unsigned numfree, ... );
Pascal/Delphi | This function does not exist
Description | The parameter numfree "tells" the function how many matrices it has to free. These matrices follow in the parameter list after numfree. De-allocation of matrices not allocated by one of the functions of the MF_matrix or MF_matrix0 family is not possible. Pascal/Delphi: since a variable number of parameters is not supported in Pascal language, this function is missing.
Example C/C++ | M_nfree( 3, MX, MY, MZ );
See also | M_free, V_freeAll, chapter 2

VF_nonlinfit | VD_nonlinfit | VE_nonlinfit
VF_nonlinfitwW | VD_nonlinfitwW | VE_nonlinfitwW
Function | fit y=f(x) data to a model-function which may be nonlinear in its parameters
Syntax C/C++ | #include <MFstd.h> float VF_nonlinfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, ui sizex, void (*modelfunc)(fVector YModel, fVector XModel, ui size), void (*derivatives)(fVector dYdAi, fVector X, ui size, unsigned iPar) ); float VF_nonlinfitwW( fVector A, fMatrix Covar, iVector AStatus, unsigned npars, fVector X, fVector Y, fVector InvVar, ui sizex, void (*modelfunc)(fVector YModel, fVector X, ui size), void (*derivatives)(fVector dYdAi, fVector X, ui size, unsigned i) );
Pascal/Delphi | uses VFnlfit; function VF_nonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; X, Y: fVector; sizex: UInt; ModelFunc, Derivatives: Pointer ): Single; function VF_nonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; X, Y, InvVar:fVector; sizex: UInt; ModelFunc, Derivatives: Pointer ): Single;
Description | The input data X, Y (and InvVar) are used to evaluate the parameter array A with npars elements ai of an arbitrary model function y = f(x). Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
X, Y, InvVar | vectors of size sizex, holding the input data
modelfunc | user-defined model function
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling VF_nonlinfit. The better your initial guess of the parameters, the faster VF_nonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!). You must provide a model function "modelfunc" which, for a given vector of x-values, must calculate the corresponding "theoretical" y-values. In C/C++, it has to be defined as
Model function for C/C++ | void _cdecl MyFunc( fVector Y, fVector X, ui size ) { for (ui i=0; i<size; i++ ) Y[i] = f( X[i] ); } f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS). In addition to the model function, VF_nonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for C/C++ | void _cdecl MyDerivs( fVector dYdAi, fVector X, ui size, unsigned ipar ) { ui i; switch( ipar ) { case 0: for(i=0; i<size; i++ ) dYdAi[i] = part_derv_of_Y_w_resp_to_A0( X[i] ); break; case 1: for(i=0; i<size; i++ ) dYdAi[i] = part_derv_of_Y_w_resp_to_A1( X[i] ); break; default: /* for all derivatives we don't know: */ VF_nonlinfit_autoDeriv( dYdAi, X, size, ipar); } } A call to VF_nonlinfit will look like: VF_nonlinfit( A, AStatus, npars, X, Y, sizex, MyFunc, MyDerivs ); In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_nonlinfit with derivaties = NULL: VF_nonlinfit( A, AStatus, npars, X, Y, sizex, MyFunc, NULL );
Model function for Pascal/Delphi | In Pascal/Delphi, the model function has to be defined as procedure MyFunc( Y, X:fVector; size:UInt ); var i:UInt; begin for i:=0 to size-1 do VF_Pelement( Y, i )^ := f( VF_element( X, i ) ); end; f( X[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS). In addition to the model function, VF_nonlinfit needs the partial derivatives of Y with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on VF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for Pascal/Delphi | procedure MyDerivs( dYdAi, X:fVector; size, ipar:UInt ); var i:UInt; begin case ipar of 0: begin for i:=0 to size-1 do VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end; 1: begin for i:=0 to size-1 do VF_Pelement( dYdAi, i )^ := part_derv_of_Y_w_resp_to_A0(VF_element( X, i )); end; else (* for all derivatives we don't know: *) VF_nonlinfit_autoDeriv( dYdAi, X, size, ipar ); end; end; A call to VF_nonlinfit will look like: VF_nonlinfit( A, AStatus, npars, X, Y, sizex, @MyFunc, @MyDerivs ); Note the address-of operator in front of "MyFunc." and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call VF_nonlinfit with derivaties = nil: VF_nonlinfit( A, AStatus, npars, X, Y, sizex, @MyFunc, nil ); In the weighted variant, VF_nonlinfitwW, the vector InvVar has to contain the inverse of the variances of the individual X-Y data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
Both C/C++ and Pascal/Delphi: | For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of VF_nonlinfit, described here.
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, VF_nonlinfit and VF_nonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run VF_nonlinfit and VD_nonlinfit in parallel. These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy.
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1
See also | VF_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 |
Function | helper 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)
Pascal/Delphi | uses VFnlfit; procedure VF_nonlinfit_autoDeriv( dYdAi, X: fVector; size, ipar:UInt ); function VF_nonlinfit_getChi2: Single; procedure VF_nonlinfit_getBestValues( BestValues: fVector ); function VF_nonlinfit_getTestDir: Integer; function VF_nonlinfit_getTestPar: UInt; function VF_nonlinfit_getTestRun: UInt; procedure VF_nonlinfit_stop; (identical syntax for the VF_nonlinfitwW_... functions)
Description | VF_nonlinfit_autoDeriv performs a numerical differentiation of a user-provided y=f(x) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to VF_nonlinfit. The model function that is differentiated by VF_nonlinfit_autoDeriv is the one passed in the same call to VF_nonlinfit (see that function for details!). The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function. VF_nonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before VF_nonlinfit has had the chance to calculate c2, VF_nonlinfit_getChi2 returns -1.0. VF_nonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest. VF_nonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions). VF_nonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation. VF_nonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first. VF_nonlinfit_stop makes VF_nonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data.
See also | chapter 13

MF_nonlinfit | MD_nonlinfit | ME_nonlinfit
MF_nonlinfitwW | MD_nonlinfitwW | ME_nonlinfitwW
Function | fit z=f(x,y) data to a model-function which may be nonlinear in its parameters
Syntax C/C++ | #include <MFstd.h> float MF_nonlinfit( fVector A, iVector AStatus, unsigned npars, fVector X, fVector Y, fMatrix MZ, unsigned htZ, unsigned lenZ, void (*modelfunc)(fMatrix MZModel, 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 MZ, fMatrix MInvVar, unsigned htZ, unsigned lenZ, void (*modelfunc)(fMatrix MZModel, unsigned htZ, unsigned lenZ, fVector X, fVector Y ), void (*derivatives)(fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar) );
Pascal/Delphi | uses MFnlfit; function MF_nonlinfit( A: fVector; AStatus: iVector; nParameters: UInt; X, Y: fVector; MZ: fMatrix; htZ, lenZ: UInt; ModelFunc, Derivatives: Pointer ): Single; function MF_nonlinfitwW( A: fVector; Covar: fMatrix; AStatus: iVector; nParameters: UInt; X, Y: fVector; MZ, MInvVar: fMatrix; htZ, lenZ: UInt; ModelFunc, Derivatives: Pointer ): Single;
Description | The input data X, Y, MZ (and MInvVar) are used to evaluate the parameter array A with npars elements ai of an arbitrary model function z = f(x,y). Arguments:
A | vector of size npars; returns the coefficients
Covar | matrix of dimensions [npars, npars]; returns the covariances of the coefficients
AStatus | vector of size npars; decides which parameters are treated as free or as fixed
npars | total number of parameters
X, Y | vectors of size lenZ and htZ, respectively, spanning the x-y coordinate system of the matrix MZ
MZ, MInvVar | matrices of dimensions [htZ, lenZ], holding the input data and, in the weighted variant, the inverse of their variances
modelfunc | user-defined model function
derivatives | user-defined function, calculating the partial derivatives with respect to all parameters
The model function (and, consequently, the vector A as well) may actually contain more parameters than you wish to treat as adjustable. This is why you have to provide an additional vector, AStatus, which contains the necessary information about which parameters are to be held fixed at their input values (AStatus[i] = 0) and which are free (AStatus[i] = 1). All parameters must be initialized in A prior to calling MF_nonlinfit. The better your initial guess of the parameters, the faster MF_nonlinfit shall converge. The argument npars denotes the total number of parameters in A (not only the free parameters!). You must provide a model function "modelfunc" which, for given vectors of x and y values, must calculate the corresponding "theoretical" z values. In C/C++, it has to be defined as
Model function for C/C++ | void _cdecl MyFunc( fMatrix MZ, unsigned htZ, unsigned lenZ, fVector X, fVector Y ) { for (ui i=0; i<htZ; i++ ) for (ui j=0; j<lenZ; j++ ) MZ[i][j] = f( X[j], Y[i] ); } f( X[j], Y[i] ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS). In addition to the model function, MF_nonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for C/C++ | void _cdecl MyDerivs( fMatrix dZdAi, unsigned htZ, unsigned lenZ, fVector X, fVector Y, unsigned ipar ) { ui i; switch( ipar ) { case 0: for(i=0; i<htZ; i++ ) for( j=0; j<lenZ; j++ ) dZdAi[i][j] = part_derv_MZ_w_resp_to_A0( X[j], Y[i] ); break; case 1: for(i=0; i<htZ; i++ ) for( j=0; j<lenZ; j++ ) dZdAi[i][j] = part_derv_MZ_w_resp_to_A1( X[j], Y[i] ); break; default: /* for all derivatives we don't know: */ MF_nonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar); } } A call to MF_nonlinfit will look like: MF_nonlinfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, MyFunc, MyDerivs ); In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_nonlinfit with derivaties = NULL: MF_nonlinfit( A, AStatus, npars, X, Y, MZ, htZ, lenZ, MyFunc, NULL );
Model function for Pascal/Delphi | In Pascal/Delphi, the model function has to be defined as procedure MyFunc( MZ:fMatrix; htZ, lenZ:UInt; X, Y:fVector ); var i, j:UInt; begin for i:=0 to htZ-1 do for j:=0 to lenZ-1 do MF_Pelement( MZ, htZ, lenZ, i, j )^ := f( VF_element( X, j ), VF_element( Y, i ) ); end; f( Xj, Yi ) is any arbitrary function, which may be as complicated as you like and your application needs. The only condition is that it have no singularities, at least within the parameter space specified by upper and lower boundaries (see NONLINFITOPTIONS). In addition to the model function, MF_nonlinfit needs the partial derivatives of MZ with respect to all parameters A[ipar], according to your model. If you know them analytically, you should write a function MyDerivs. If you happen to know only some, but not all of the partial derivatives, you may rely on MF_nonlinfit_autoDeriv to calculate the unknown derivatives numerically.
Partial derivatives coded for Pascal/Delphi | procedure MyDerivs( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar:UInt ); var i, j:UInt; begin case ipar of 0: begin for i:=0 to htZ-1 do for j:=0 to lenZ-1 do MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A0(VF_element( X, j ), VF_element( Y, i )); end; 1: begin for i:=0 to htZ-1 do for j:=0 to lenZ-1 do MF_Pelement( dZdAi, htZ, lenZ, i, j )^ := part_derv_MZ_w_resp_to_A1(VF_element( X, j ), VF_element( Y, i )); end; else (* for all derivatives we don't know: *) MF_nonlinfit_autoDeriv( dZdAi, htZ, lenZ, X, Y, ipar ); end; end; A call to MF_nonlinfit will look like: MF_nonlinfit( A, AStatus, npars, MZ, htZ, lenZ, X, Y, @MyFunc, @MyDerivs ); Note the address-of operator in front of "MyFunc." and "MyDerivs". In Turbo Pascal, both MyFunc and MyDerivs must be compiled with the Force-Far-Calls option {$F+}. In case you do not know any of the partial derivatives, do not define MyDerivs, but call MF_nonlinfit with derivaties = nil: MF_nonlinfit( A, AStatus, npars, MZ, htZ, lenZ, X, Y, @MyFunc, nil ); In the weighted variant, MF_nonlinfitwW, the matrix MInvVar has to contain the inverse of the variances of the individual X-Y-Z data points, and the matrix MCovar will be filled with the covariances of the parameters ai on output: MCovari,j = covariance( ai, aj ).
Both C/C++ and Pascal/Delphi: | For the many different options controlling nonlinear data-fitting functions, please consult chapter 13.3. Helper functions for breaking off excessively long fitting runs and for the monitoring of these often very time-consuming procedures are summarized in chapter 13.5 and, in the special case of MF_nonlinfit, described here.
Multi-threading restrictions | In order to allow the monitoring functions to access intermediate results, these had to be made global. Therefore, only one instance of a given nonlinear fitting function can be active at a time. If the same function would run in two or more parallel threads, they would overwrite each other's intermediate results. Additionally, in the Delphi version, MF_nonlinfit and MF_nonlinfitwW cannot run simultaneously either. The same is true on the VD_ and on the VE_ level. It is, however, possible, to run MF_nonlinfit and MD_nonlinfit in parallel. These functions may not be called while the FPU is set to reduced accuracy, or else they might hang in an infinite loop. See V_setFPAccuracy.
Return value | in case of success: goodness-of-fit parameter c2 (chi-square); in case of failure: -1
See also | VF_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 |
Function | helper 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)
Pascal/Delphi | uses MFnlfit; procedure MF_nonlinfit_autoDeriv( dZdAi:fMatrix; htZ, lenZ:UInt; X, Y:fVector; ipar: UInt ); function MF_nonlinfit_getChi2: Single; procedure MF_nonlinfit_getBestValues( BestValues: fVector ); function MF_nonlinfit_getTestRun: UInt; function MF_nonlinfit_getTestPar: UInt; function MF_nonlinfit_getTestDir: Integer; procedure MF_nonlinfit_stop; (identical syntax for the MF_nonlinfitwW_... functions)
Description | MF_nonlinfit_autoDeriv performs a numerical differentiation of a user-provided z=f(x,y) model function with respect to the parameter aipar of the model. This function can be called only from within a function passed as the argument "derivatives" to MF_nonlinfit. The model function that is differentiated by MF_nonlinfit_autoDeriv is the one passed in the same call to MF_nonlinfit (see that function for details!). The following functions allow to monitor the progress of a nonlinear fitting operation. They can either be called from within the provided model function or, for multi-thread applications, from a second thread running in parallel to the thread containing the fitting function. MF_nonlinfit_getChi2 returns the best figure-of-merit (c2 or, for robust fits, |c|) obtained so far. If you call this function before MF_nonlinfit has had the chance to calculate c2, MF_nonlinfit_getChi2 returns -1.0. MF_nonlinfit_getBestValues stores the best parameters ai obtained so far into the user-supplied vector ABest. MF_nonlinfit_getTestDir returns the test direction (+1 for upwards, -1 for downwards) during "breakout" attempts from possible local optima which would otherwise prevent the routine from finally reaching the global optimum (level-of-method greater than 3 specified by VF_setNonlinfitOptions). MF_nonlinfit_getTestPar returns the index of the parameter currently under "breakout" investigation. MF_nonlinfit_getTestRun returns the index of the current "breakout" test run. For each fitted parameter, one test run is performed. The order in which the parameters are checked is determined internally in such a way as to test the most sensitive parameters first. MF_nonlinfit_stop makes MF_nonlinfit finish its current Levenberg-Marquardt or Downhill-Simplex cycle, update the output parameters and return. Thereby, long fitting sessions (especially tedious "break-out" attempts) may be broke off without the loss of any data.
See also | chapter 13

MF_outerprod | MD_outerprod | ME_outerprod
MCF_outerprod | MCD_outerprod | MCE_outerprod
Function | formation of a matrix by the "outer product" of two vectors
Syntax C/C++ | #include <MFstd.h> void MF_outerprod( fMatrix MA, fVector X, fVector Y, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_outerprod( MA:fMatrix; X, Y:fVector; ht, len:UInt );
Description | MAi,j = Xi * Yj
See also | VF_mulM, chapter 3

MF_Parzen | MD_Parzen | ME_Parzen
Function | two-dimensional Parzen window for spatial frequency analysis
Syntax C/C++ | #include <MFstd.h> void MF_Parzen( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Parzen( MA:fMatrix; ht, len:UInt );
Description | MAi,j = (1 - |(i - 0.5*(ht - 1)) / 0.5*(ht + 1)|) * (1 - |(j - 0.5*(len - 1)) / 0.5*(len + 1)|)
See also | MF_Hanning, MF_Welch, MF_spectrum, chapter 3

MF_Pelement | MD_Pelement | ME_Pelement
MCF_Pelement | MCD_Pelement | MCE_Pelement
Function | get pointer to a matrix element
Syntax C/C++ | #include <MFstd.h> float * MF_Pelement( fMatrix X, unsigned ht, unsigned len, unsigned m, unsigned n );
Pascal/Delphi | uses MFstd; function MF_Pelement( MA:fMatrix; ht, len, m, n:UInt ): PSingle;
Description | A pointer to the element MAm,n is returned. This function is needed to access elements of dynamically allocated matrices, for which older versions of Borland C++ had a pointer arithmetics bug, and Pascal/Delphi - unlike C - does not provide an own mechanism at all. Writing a matrix element through this function, use the dereferenced-pointer syntax:
C/C++ | *MF_Pelement( MA, ht, len, m, n ) = 3.5;
Pascal/Delphi | MF_Pelement( MA, ht, len, m, n )^ := 3.5; Read-only access to matrix elements is provided by the related function, MF_element
Return value | pointer to the matrix element MAm,n
See also | MF_element, chapter 2

VF_polyfit | VD_polyfit | VE_polyfit
VF_polyfitwW | VD_polyfitwW | VE_polyfitwW
Function | fitting of one X-Y data set to a polynomial
Syntax C/C++ | #include <MFstd.h> void VF_polyfit( fVector A, unsigned deg, fVector X, fVector Y, ui sizex ); void VF_polyfitwW( fVector A, fMatrix Covar, unsigned deg, fVector X, fVector Y, fVector InvVar, ui sizex );
Pascal/Delphi | uses MFstd; procedure VF_polyfit( A:fVector; deg:UInt; X, Y:fVector; sizex:UInt ); procedure VF_polyfitwW( A:fVector; Covar:fMatrix; deg:UInt; X, Y, InvVar:fVector; sizex:UInt );
Description | The input data are used to determine the coefficients ai of a polynomial Pi = a0 + a1Xi + a2Xi2 ... anXin so as to minimize the deviation between the "theoretical" Pi values, calculated by the polynomial, and the actual Yi values. To be more precise, the figure-of-merit chi-square, c2 = sum( 1/si2 * (Pi - Yi)2 ) is minimized. In the weighted variant, VF_polyfitwW, 1/si2 has to be provided as the vector InvVar. In the non-weighted variant, all si are assumed as 1.0. Arguments:
A | vector of size deg+1; returns the coefficients
Covar | matrix of dimensions [deg+1, deg+1]; returns the covariances of the coefficients
deg | the degree of the fitting polynomial
X, Y, InvVar | vectors of size sizex, holding the input data
See also | VF_linregress, VF_linfit, VF_chi2, chapter 13

MF_print | MD_print | ME_print
MCF_print | MCD_print | MCE_print
Function | print a matrix in ASCII format to stdout, assuming a linewidth of 80 characters (DOS and 16-bit Windows with EasyWin only)
Syntax C/C++ | #include <MFstd.h> void MF_print( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_print( MA:fMatrix; ht, len:UInt );
Description | The matrix MA is written to stream. Each line corresponds to one row of the matrix. The lines are numbered. The linewidth is assumed to be 80 characters. If this linewidth is too small to write all columns, rows are cut off. Cartesian complex numbers are printed in braces, with the real and imaginary parts separated by a komma: {Re, Im}. In contrast to MF_write, it is not possible to override the automatic choice of the format used for printing. The number of digits per element is determined by the available space, which depends in turn on the parameter len. In contrast to MF_cprint, no paging is performed. This family of functions is available under Windows only in connection with EasyWin, and should not be used within TurboVision programs.
See also | VF_print, MF_cprint, MF_fprint, chapter 14

MF_random | MD_random | ME_random
MCF_random | MCD_random | MCE_random
Function | fill a matrix with high-quality random numbers
Syntax C/C++ | #include <MFstd.h> long MF_random( fMatrix MA, unsigned ht, unsigned len, long seed, float MinVal, float MaxVal );
Pascal/Delphi | uses MFstd; function MF_random( MA:fMatrix; ht, len:UInt; seed:LongInt; MinVal, MaxVal:Single ): LongInt;
Description | The matrix MA is filled with random numbers. Within the ranges defined by MinVal and MaxVal, and within the restrictions of floating-point representation, all numbers are equally probable (including the extreme values themselves), i.e., so-called "uniform deviates" are produced. The parameter seed may be any number. Successive calls to one and the same of these functions will yield identical sequences, if seed is chosen equal; if seed is chosen differently for successive calls, the results will be uncorrelated. Internally, these functions employ a 32-bit integer random number generator by H.W.Lewis, with additional steps (so-called "Bays-Durham shuffle") to break sequential correlations. This ensures very good randomness, far superior to simpler generators (like the rand function of C/C++ compilers or the random function of Pascal/Delphi). A long value is returned which may be used as new seed for subsequent calls.
Error handling | none
Return value | last 32-bit random number generated; this may be used as a new seed value for future calls.
See also | VF_random, chapter 3

MF_read | MD_read | ME_read
MCF_read | MCD_read | MCE_read
Function | read a matrix in ASCII format from a stream
Syntax C/C++ | #include <MFstd.h> void MF_read( fMatrix X, unsigned ht, unsigned len, FILE *stream );
Pascal/Delphi | uses MFstd; {Delphi version:} procedure MF_read( MA:fMatrix; ht, len:UInt; var Stream:TextFile ); {Turbo Pascal version:} procedure MF_read( MA:fMatrix; ht, len:UInt; var Stream:Text );
Description | The matrix MA of ht*len elements is read in ASCII format from stream. Normally, this function will be used to import matrices from a program which cannot store numbers in machine format. It can also be used to retrieve matrices previously stored by MF_write. For storing and retrieving intermediate results, however, the function pair MF_store / MF_recall is to be preferred over MF_write / MF_read (see MF_write). Cartesian complex versions: Real und imaginary parts may, but need not, be enclosed in braces { } or brackets ( ). However, you must be consequent: Either all or no element may be written with braces or brackets. A komma may (but need not) separate the two parts. The imaginary part must always be explicitly specified, even if it is zero. Examples for legal formats are: 0.3 0.5 (neither braces nor separating komma) 0.3, 0.5 (no braces; separating komma) {0.3 0.5} (braces; no separating komma) (0.3, 0.5) (brackets and separating komma)
C/C++ specific: | The entries to be read must be separated by whitespace (' ', '\n', or '\t'). Additionally, one (!) "non-whitespace" character is tolerated after each entry, if it follows directly after the last digit. After it, there must be one or more whitespace characters.
Pascal/Delphi specific: | The entries to be read must be separated by whitespace (' ', #13, or #9). Whereas the C/C++ version of these functions follows the conventions of the C functions strtod, strtol, etc., the Pascal/Delphi version has to follow the rules applying to the Pascal/Delphi function Read. This makes the Pascal/Delphi version much less flexible than the C version: - no separation characters allowed other than ' ' and #9, - no automatic truncation of overflowing numbers
Error handling | C/C++: Overflowing numbers are silently truncated to ±HUGE_VAL. Pascal/Delphi: Overflowing numbers or numbers otherwise not conforming to the format requirements lead to an I/O error.
See also | MF_write, VF_nread, MF_store, MF_recall, chapter 14

MF_recall | MD_recall | ME_recall
MCF_recall | MCD_recall | MCE_recall
Function | Read a matrix in binary format from a stream
Syntax C/C++ | #include <MFstd.h> void MF_recall( fMatrix MA, unsigned ht, unsigned len, FILE *stream);
Pascal/Delphi | uses MFstd; procedure MF_recall( MA:fMatrix; ht, len:UInt; var Stream:FILE );
Description | The matrix MA of ht*len elements is read from stream in binary format. Normally, these functions are used to retrieve data stored by the respective function of the MF_store family. In C/C++, matrices are stored by rows, where as Pascal/Delphi and Fortran work with matrices stored by columns. This means that you will get the transpose of a matrix stored by a C/C++ program, if you read it with a Pascal/Delphi program, and vice versa. In this case, simply call MF_transpose( MA, MA, ht, len );.
See also | MF_store, chapter 14

MF_Row_addC | MD_Row_addC | ME_Row_addC
MCF_Row_addC | MCD_Row_addC | MCE_Row_addC
Function | add a constant to all elements of one row
Syntax C/C++ | #include <MFstd.h> void MF_Row_addC( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Row_addC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
Description | MAiRow,i += C, i=0,...,len-1
See also | MF_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
Function | element-wise addition of one row and a vector
Syntax C/C++ | #include <MFstd.h> void MF_Row_addV( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_addV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
Description | MAiRow,i += Xi, i=0,...,len-1
See also | MF_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
Function | delete one row from a matrix
Syntax C/C++ | #include <MFstd.h> void MF_Row_delete( fMatrix MB, fMatrix MA, unsigned htA, unsigned lenA, unsigned iRow );
Pascal/Delphi | uses MFstd; procedure MF_Row_delete( MB, MA:fMatrix; htA, lenA, iRow:UInt );
Description | MBi,j = MAi,j, i=0,...,iRow-1, j=0,...,len-1 MBi,j = MAi+1,j, i=iRow,...,htA-2, j=0,...,lenA-1 The parameters htA and lenA refer to the input matrix
See also | MF_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
Function | divide all elements of one row by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Row_divC( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Row_divC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
Description | MAiRow,i /= C, i=0,...,len-1
See also | MF_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
Function | reverse division: divide a constant by all elements of one row
Syntax C/C++ | #include <MFstd.h> void MF_Row_divrC( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Row_divrC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
Description | MAiRow,i = C / MAiRow,i, i=0,...,len-1
See also | MF_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
Function | element-wise reverse division: divide a vector by one row of a matrix, storing the result back into the row
Syntax C/C++ | #include <MFstd.h> void MF_Row_divrV( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_divrV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
Description | MAiRow,i = Xi / MAiRow,i, i=0,...,len-1
See also | MF_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
Function | element-wise division of one row of a matrix by a vector
Syntax C/C++ | #include <MFstd.h> void MF_Row_divV( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_divV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
Description | MAiRow,i /= Xi, i=0,...,len-1
See also | MF_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
Function | initialize all elements of one row with zero
Syntax C/C++ | #include <MFstd.h> void MF_Row_equ0( fMatrix MA, unsigned ht, unsigned len, unsigned iRow );
Pascal/Delphi | uses MFstd; procedure MF_Row_equ0( MA:fMatrix; ht, len, iRow:UInt );
Description | MAiRow,i = 0, i=0,...,len-1
See also | MF_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
Function | initialize all elements of one row with a constant
Syntax C/C++ | #include <MFstd.h> void MF_Row_equC( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Row_equC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
Description | MAiRow,i = C, i=0,...,len-1
See also | MF_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
Function | copy a vector into one row
Syntax C/C++ | #include <MFstd.h> void MF_Row_equV( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_equV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
Description | MAiRow,i = Xi, i=0,...,len-1
See also | MF_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
Function | copy one row into a vector
Syntax C/C++ | #include <MFstd.h> void MF_Row_extract( fVector Y, fMatrix MA, unsigned ht, unsigned len, unsigned iRow );
Pascal/Delphi | uses MFstd; procedure MF_Row_extract( Y:fVector; MA:fMatrix; ht, len, iRow:UInt );
Description | Xi = MAiRow,i, i=0,...,len-1
See also | MF_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
Function | augment a matrix by insertion of one row
Syntax C/C++ | #include <MFstd.h> void MF_Row_insert( fMatrix MB, fMatrix MA, unsigned htB, unsigned lenB, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_insert( MB, MA:fMatrix; htB, lenB, iRow:UInt; X:fVector );
Description | MBi,j = MAi,j, i=0,...,iRow-1, j=0,...,len-1 MBiRow,j = Xj, j=0,...,lenB-1 MBi,j = MAi-1,j, i=iRow,...,htB-1, j=0,...,lenB-1 The parameters htB and lenB refer to the output matrix
See also | MF_Row_delete, chapter 5

MF_Row_mulC | MD_Row_mulC | ME_Row_mulC
MCF_Row_mulC | MCD_Row_mulC | MCE_Row_mulC
Function | multiply all elements of one row by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Row_mulC( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Row_mulC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
Description | MAiRow,i *= C, i=0,...,len-1
See also | MF_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
Function | element-wise multiplication of one row and a vector
Syntax C/C++ | #include <MFstd.h> void MF_Row_mulV( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_mulV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
Description | MAiRow,i *= Xi, i=0,...,len-1
See also | MF_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
Function | subtract a constant from all elements of one row
Syntax C/C++ | #include <MFstd.h> void MF_Row_subC( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Row_subC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
Description | MAiRow,i -= C, i=0,...,len-1
See also | MF_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
Function | reverse subtraction: a constant minus one row
Syntax C/C++ | #include <MFstd.h> void MF_Row_subrC( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Row_subrC( MA:fMatrix; ht, len, iRow:UInt; C:Single );
Description | MAiRow,i = C - MAiRow,i, i=0,...,len-1
See also | MF_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
Function | element-wise reverse subtraction: subtract one row from a vector, storing the result back into the row
Syntax C/C++ | #include <MFstd.h> void MF_Row_subrV( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_subrV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
Description | MAiRow,i = Xi - MAiRow,i, i=0,...,len-1
See also | MF_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
Function | element-wise subtraction of a vector from one row
Syntax C/C++ | #include <MFstd.h> void MF_Row_subV( fMatrix MA, unsigned ht, unsigned len, unsigned iRow, fVector X );
Pascal/Delphi | uses MFstd; procedure MF_Row_subV( MA:fMatrix; ht, len, iRow:UInt; X:fVector );
Description | MAiRow,i -= Xi, i=0,...,len-1
See also | MF_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
Function | store the absolute maxima of all individual rows in a column vector
Syntax C/C++ | #include <MFstd.h> void MF_Rows_absmax( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_absmax( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The maximum absolute value of each row i is stored as the element Yi for i=0,...,ht-1
See also | MF_Rows_max, MF_Rows_absmin, MF_Cols_absmax, MF_Dia_absmax, chapter 7

MF_Rows_absmin | MD_Rows_absmin | ME_Rows_absmin
MCF_Rows_absmin | MCD_Rows_absmin | MCE_Rows_absmin
Function | store the absolute minima of all individual rows in a column vector
Syntax C/C++ | #include <MFstd.h> void MF_Rows_absmin( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_absmin( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The minimum absolute value of each row i is stored as the element Yi for i=0,...,ht-1
See also | MF_Rows_min, MF_Rows_absmax, MF_Cols_absmin, MF_Dia_absmin, chapter 7

MF_Rows_add | MD_Rows_add | ME_Rows_add
MCF_Rows_add | MCD_Rows_add | MCE_Rows_add
Function | make one row the sum of itself and another row
Syntax C/C++ | #include <MFstd.h> void MF_Rows_add( fMatrix MA, unsigned ht, unsigned len, unsigned destRow, unsigned sourceRow );
Pascal/Delphi | uses MFstd; procedure MF_Rows_add( MA:fMatrix; ht, len, destRow, sourceRow:UInt );
Description | MAdestRow, j += MAsourceRow, j, i=0,...,len-1
See also | MF_Rows_sub, MF_Rows_Cadd, MF_Rows_lincomb, chapter 8

MF_Rows_Cadd | MD_Rows_Cadd | ME_Rows_Cadd
MCF_Rows_Cadd | MCD_Rows_Cadd | MCE_Rows_Cadd
Function | make one row the sum of itself and another row, scaled by a constant
Syntax C/C++ | #include <MFstd.h> void MF_Rows_Cadd( fMatrix MA, unsigned ht, unsigned len, unsigned destRow, unsigned sourceRow, float C );
Pascal/Delphi | uses MFstd; procedure MF_Rows_Cadd( MA:fMatrix; ht, len, destRow, sourceRow:UInt; C:Single );
Description | MAdestRow, j += C * MAsourceRow, j, i=0,...,len-1
See also | MF_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
Function | exchange two rows
Syntax C/C++ | #include <MFstd.h> void MF_Rows_exchange( fMatrix MA, unsigned ht, unsigned len, unsigned i1, unsigned i2 );
Pascal/Delphi | uses MFstd; procedure MF_Rows_exchange( MA:fMatrix; ht, len, i1, i2:UInt );
Description | The elements of the rows i1 and i2 are exchanged.
See also | MF_Cols_exchange, chapter 8

MF_Rows_lincomb | MD_Rows_lincomb | ME_Rows_lincomb
MCF_Rows_lincomb | MCD_Rows_lincomb | MCE_Rows_lincomb
Function | linear combination of two rows
Syntax C/C++ | #include <MFstd.h> void MF_Rows_lincomb( fMatrix MA, unsigned ht, unsigned len, unsigned destRow, float destC, unsigned srceRow, float srceC );
Pascal/Delphi | uses MFstd; procedure MF_Rows_lincomb( MA:fMatrix; ht, len:UInt; destRow:UInt; destC:Single; srceRow:Uint; srceC:Single );
Description | MAdestRow, j = destC * MAdestRow, j+ srceC * MAsrceRow, j, j=0,...,len-1
See also | MF_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
Function | store the maxima of all individual rows in a column vector
Syntax C/C++ | #include <MFstd.h> void MF_Rows_max( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_max( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The maximum value of each row i is stored as the element Yi for i=0,...,ht-1
See also | MF_Rows_absmax, MF_Rows_min, MF_Cols_max, chapter 7

MF_Rows_min | MD_Rows_min | ME_Rows_min
MCF_Rows_min | MCD_Rows_min | MCE_Rows_min
Function | store the minima of all individual rows in a column vector
Syntax C/C++ | #include <MFstd.h> void MF_Rows_min( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_min( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | The smallest or most negative element of each row i is stored as the element Yi for i=0,...,ht-1
See also | MF_Rows_absmin, MF_Rows_max, MF_Cols_min, chapter 7

MF_Rows_prod | MD_Rows_prod | ME_Rows_prod
MCF_Rows_prod | MCD_Rows_prod | MCE_Rows_prod
Function | products over all elements of each individual row, stored in a column vector
Syntax C/C++ | #include <MFstd.h> void MF_Rows_prod(fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_prod(Y:fVector; MA:fMatrix; ht, len:UInt );
Description | Yi = prod( MAi,j, j=0,...,len-1), i=0,...,ht-1
See also | MF_Rows_runprod, MF_Rows_sum, chapter 7

MF_Rows_reflect | MD_Rows_reflect | ME_Rows_reflect
Function | Derive the second halves of all rows from their first halves by reflection at the vertical line through the center of the matrix.
Syntax C/C++ | #include <MFstd.h> void MF_Rows_reflect( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_reflect( MA:fMatrix; ht, len:UInt );
Description | MAi, len-j-1 = MAi, j, i=0,...,ht-1; j=0,...,(len-1)/2;
See also | MF_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
Function | rotate all rows by a specified number of positions; thereby, whole columns are moved
Syntax C/C++ | #include <MFstd.h> void MF_Rows_rotate( fMatrix MA, unsigned ht, unsigned len, int pos );
Pascal/Delphi | uses MFstd; procedure MF_Rows_rotate( MA:fMatrix; ht, len:UInt; pos:Integer );
Description | MAi,j = MAi, len-pos+j, j=0,..,pos-1 MAi,j = MAi, j-pos, j=pos,...,len-1
See also | MF_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
Function | running product over row elements
Syntax C/C++ | #include <MFstd.h> void MF_Rows_runprod( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_runprod( MA:fMatrix; ht, len:UInt );
Description | For all rows separately, each element is the product of itself and all preceding elements. This function should be used with care: overflow is easily reached, and underflow may lead to all elements from a certain position on being zero.
See also | MF_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
Function | running sum over row elements
Syntax C/C++ | #include <MFstd.h> void MF_Rows_runsum( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_runsum( MA:fMatrix; ht, len:UInt );
Description | For all rows separately, each element is the sum of itself and all preceding elements.
See also | MF_Rows_sum, MF_Cols_runsum, chapter 7

MF_Rows_sub | MD_Rows_sub | ME_Rows_sub
MCF_Rows_sub | MCD_Rows_sub | MCE_Rows_sub
Function | make one row the difference of itself and another row
Syntax C/C++ | #include <MFstd.h> void MF_Rows_sub( fMatrix MA, unsigned ht, unsigned len, unsigned destRow, unsigned sourceRow );
Pascal/Delphi | uses MFstd; procedure MF_Rows_sub( MA:fMatrix; ht, len, destRow, sourceRow:UInt; );
Description | MAdestRow, j -= MAsourceRow, j, i=0,...,len-1
See also | MF_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
Function | sums over all elements of each individual row, stored in a column vector
Syntax C/C++ | #include <MFstd.h> void MF_Rows_sum( fVector Y, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Rows_sum( Y:fVector; MA:fMatrix; ht, len:UInt );
Description | Yi = sum( MAi,j, j=0,...,len-1), i=0,...,ht-1
See also | MF_Rows_runsum, MF_Rows_prod, chapter 7

MF_safeSolve | MD_safeSolve | ME_safeSolve
Function | solve a linear system MA * X = B; in case the system is singular, get one solution out of the infinite solution space
Syntax C/C++ | #include <MFstd.h> int MF_safeSolve( fVector X, fMatrix MA, fVector B, unsigned len );
Pascal/Delphi | uses MFstd; function MF_safeSolve( X:fVector; MA:fMatrix; B:fVector; len:UInt ):Integer;
Description | MF_safeSolve is similar to MF_solve with the difference that, in case there is no unique solution of the linear system (i.e., LU decomposition fails), singular value decomposition is employed to obtain at least one solution out of the infinite solution space. Recall that the problem with singular linear systems is not that they don't have a solution, but rather that they are under-determined and have infinitely many solutions. In other words, one or more elements of the solution vector can be chosen arbitrarily. This is what MF_safeSolve does, with the additional constraint that the "smallest" solution vector in the least-squares sense is determined. A return value of 0 indicates success via LUD, 1 signals success via SVD, and -1 is returned in the very rare case that even SVD fails.
See also | MF_solve, chapter 10

M_setDensityBounds
Function | Calculate a color scale for color density plots
Syntax C/C++ | #include <Mgraph.h> void M_setDensityBounds( extended zmin, extended zmax, COLORREF mincolor, COLORREF maxcolor );
Pascal/Delphi | uses Mgraph; procedure M_setDensityBounds( zmin, zmax: Extended; mincolor, maxcolor: COLORREF );
Description | A color scale is calculated between the colors mincolor and maxcolor, corresponding to zmin and zmax. In any following MF_xyzDataDensityMap or MF_zDataDensityMap plot, the z values will be translated into colors by interpolation between the extreme values set by M_setDensityBounds. You will rarely call this function directly. It is internally called by all functions of the MF_xyzAutoDensityMap and MF_zAutoDensityMap families.
See also | M_setDensityMapBounds, M_findDensityMapBounds, chapter 15

M_setDensityMapBounds
Function | Set a color scale and draw an X-Y coordinate system for matrix color-density plots
Syntax C/C++ | #include <Mgraph.h> void M_setDensityMapBounds( extended xmin, extended xmax, extended ymin, extended ymax, extended zmin, extended zmax, COLORREF mincolor, COLORREF maxcolor );
Pascal/Delphi | uses Mgraph; procedure M_setDensityMapBounds( xmin, xmax, ymin, ymax, zmin, zmax: Extended; mincolor, maxcolor: COLORREF );
Description | Similarly to the function V_drawAxes for X-Y vector plots, this function calculates a color scale from the parameters mincolor, maxcolor, zmin and zmax, and prepares an X-Y coordinate system with the x and y ranges specified by xmin, xmax, ymin, and ymax for color-density plots of matrices. Unlike M_findDensityMapBounds, no adjustment of the x and y ranges is made. The user will rarely call this function himself. It is internally called by all functions of the MF_xyzAutoDensityMap and MF_zAutoDensityMap families.
See also | MF_xyzAutoDensityMap, MF_zAutoDensityMap, chapter 15

VF_setLinfitNeglect | VD_setLinfitNeglect | VE_setLinfitNeglect
Function | define significance threshold for data fitting to linear models
Syntax C/C++ | #include <MFstd.h> void VF_setLinfitNeglect( float Thresh );
Pascal/Delphi | uses MFstd; procedure VF_setLinfitNeglect( Thresh:Single );
Description | As described in connection with VF_linfit, this function allows to define a significance threshold below which fit parameters ai are neglected. The default of this threshold is 4*FLT_EPSILON, 8*DLB_EPSILON, or 16*LDBL_EPSILON. The current threshold can be retrieved by VF_getLinfitNeglect.
See also | VF_getLinfitNeglect, VF_linfit, chapter 13

VF_setNonlinfitOptions | VD_setNonlinfitOptions | VE_setNonlinfitOptions
Function | set options for the nonlinear fitting routines
Syntax C/C++ | #include <MFstd.h> void VF_setNonlinfitOptions( VF_NONLINFITOPTIONS *Options );
Pascal/Delphi | uses MFstd; procedure VF_setNonlinfitOptions( Options: VF_NONLINFITOPTIONS );
Description | The nonlinear fitting routines like VF_nonlinfit offer the user a lot of different options, packed into a structure VF_NONLINFITOPTIONS (VD_NONLINFITOPTIONS and VE_NONLINFITOPTIONS for the higher accuracy data-types). These options may be set by the function V_setNonlinfitOptions. To retrieve current settings, use V_getNonlinfitOptions. The options set with this function are valid for all fitting-functions of the same accuracy level. Thus, e.g., VD_setNonlinfitOptions sets the options governing VD_nonlinfit, VD_multiNonlinfit, MD_nonlinfit, MD_multiNonlinfit and their siblings with data-weighting ("wW" versions).
Example C/C++ | VD_NONLINFITOPTIONS Opt; VD_getNonlinfitOptions( &Opt ); Opt.FigureOfMerit = 0; // choose least-square fitting Opt.AbsTolChi = 1.e-6; Opt.FracTolChi = 1.e-3; // make the fit fast, but not very accurate Opt.LevelOfMethod = 3; // choose alternating Levenberg-Marquardt and Downhill-Simplex runs VD_setNonlinfitOptions( &Opt );
Example Pascal/Delphi | Opt: VD_NONLINFITOPTIONS; VD_getNonlinfitOptions(Opt ); Opt.FigureOfMerit := 0; (* choose least-square fitting *) Opt.AbsTolChi := 1.e-6; Opt.FracTolChi := 1.e-3; (* make the fit fast, but not very accurate *) Opt.LevelOfMethod := 3; (* choose alternating Levenberg-Marquardt and Downhill-Simplex runs *) VD_setNonlinfitOptions(Opt );
See also | chapter 13.3

MF_setWriteFormat | MD_setWriteFormat | ME_setWriteFormat
MCF_setWriteFormat | MCD_setWriteFormat | MCE_setWriteFormat
Function | Definition of the format to be used by M?_write: C/C++ only!
Syntax C/C++ | #include <MFstd.h> void MF_setWriteFormat( char *FormatString );
Pascal/Delphi | This function does not exist.
Description | These functions are identical to the VF_setWriteFormat family. The number format with which the M?_write functions print matrix elements into a stream can be adjusted by means of this function. When defining a write format, one should always be aware of the restrictions imposed by the read functions (not all formats you can write will be read correcly, see MF_read). MF_setWriteFormat should not be used for the definition of whitespace between the columns. This is the task of MF_setWriteSeparate. For details about the formats used for each of the various data types, please refer to the following table. The last column of this table gives the maximum length of the format string.
Version | Standard Format | Alternative Example | max. length
MF_ | "% 11.8e" | "% 8.4f" | 16
MD_ | "% 19.16le" | "% 16.8lf" | 16
ME_ | "% 22.19Le" | "% 22.19LG" | 16
MCF_ | "% 11.8e, % 11.8e" | "{% 8.4f, % 8.4f}" | 32
MCD_ | "% 19.16le, % 19.16le" | "{% 19.16lE % 19.16lE}" | 32
MCE_ | "% 22.19Le, % 22.19Le" | "{% 22.19Lg % 22.19Lg}" | 32
Error handling | Format strings longer than the maximum length specified in the above table lead to a program abort with the error message "Invalid Parameter(s)". The contents of the format string is not checked. So you have to be very careful to specify a format which is valid for the respective data type.
See also | MF_setWriteSeparate, MF_write, VF_write, MF_read, chapter 14

MF_setWriteSeparate | MD_setWriteSeparate | ME_setWriteSeparate
MCF_setWriteSeparate | MCD_setWriteSeparate | MCE_setWriteSeparate
Function | define a character string used to separate columns in the M?_write functions
Syntax C/C++ | #include <MFstd.h> void MF_setWriteSeparate( char *SepString );
Pascal/Delphi | uses MFstd; procedure MF_setWriteSeparate( SepString:PChar );
Description | These functions are identical to the functions of the VF_setNWriteSeparate family. They are used to define the character string to be inserted between the columns of a table written by MF_write. MF_setWriteSeparate does not influence the end of each line which is always a line-feed character ('\n' for C/C++ and #13 for Pascal/Delphi). SepString may contain up to twelve characters. The default setting is a single tab character ("\t" for C/C++ and #9 for Pascal/Delphi).
Error handling | In the case of SepString longer than twelve characters, the program is aborted with the error message "Invalid Parameter(s)". The contents of SepString is not checked.
See also | MF_setWriteFormat, MF_write, MF_read, chapter 14

MF_solve | MD_solve | ME_solve
MCF_solve | MCD_solve | MCE_solve
Function | solve a linear system
Syntax C/C++ | #include <MFstd.h> int MF_solve( fVector X, fMatrix MA, fVector B, unsigned len );
Pascal/Delphi | uses MFstd; function MF_solve( X:fVector; MA:fMatrix; B:fVector; len:UInt ): IntBool;
Description | This function solves the system MA * X = B of simultaneous linear equations, using LU decomposition. It works well in all cases where there is one unique solution. If successful, it returns FALSE (0). If, on the other hand, the system is ill-determined, which happens in all cases where one or more of the equations are linear combinations of other equations of the same system, the resulting matrix becomes singular and the function fails with an error message, returning TRUE (1). To avoid outright failure in an application where ill-determined matrices might occur, you should use MF_LUDsetEdit to define a minimum "pivot" for the LU decomposition process. If you do so, MF_solve will always yield a "more or less" meaningful solution and returns always FALSE (0). Then, a call to MF_LUDresult will tell you if pivot-editing has actually been necessary. Alternatively, you might switch to MF_safeSolve or MF_solveBySVD.
Return value | FALSE (0), if the linear system could by solved; TRUE (1) in the case of a singular system without pivot-editing
See also | MF_LUdecompose, MF_inv, chapter 10

MF_solveBySVD | MD_solveBySVD | ME_solveBySVD
Function | solve a possibly over- or underdetermined linear system by singular value decomposition
Syntax C/C++ | #include <MFstd.h> int MF_solveBySVD( fVector X, fMatrix MA, fVector B, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; function MF_solveBySVD( X:fVector; MA:fMatrix; B:fVector; htA, lenA:UInt ): IntBool;
Description | The system MA * X = B of simultaneous linear equations is solved for X, using Singular Value Decomposition. Here, underdetermined systems do not lead to an error. Rather, you get one particular solution out of the solution space. If you have more equations than unknowns, i.e., in the case of an overdetermined system, the solution vector contains a least-square "compromise" between the equations. The function should always return FALSE (0). Only in the very rare case of SVD failure, TRUE (1) is returned. The length of the desired solution vector, sizX must be equal to the width of the input matrix, lenA, whereas the length of the right-hand-side vector, sizB must be equal to htA. The threshold for singular-value editing should be set using MF_SVDsetEdit.
Return value | usually FALSE (0); only in the very rare case of failure, TRUE (1)
See also | MF_SVdecompose, MF_solve, chapter 10

MF_spectrum | MD_spectrum | ME_spectrum
Function | spatial frequency spectrum
Syntax C/C++ | #include <MFstd.h> void MF_spectrum( fMatrix MSpec, unsigned htSpec, unsigned lenSpec, fMatrix MX, unsigned htX, unsigned lenX, fMatrix MWin );
Pascal/Delphi | uses MFstd; procedure MF_spectrum( MSpec:fMatrix; htSpec, lenSpec:UInt; MX:fMatrix; htX, lenX:UInt; MWin:fMatrix );
Description | The data set MX is analyzed for the mean square amplitude of its spatial frequency spectrum. The result is stored in MSpc. Internally, the spectrum is calculated by dividing the input data into overlapping segments, similarly to the one-dimensional case described for VF_spectrum. MWin is a window that is applied to the data segments. Three functions are available that give suitable Windows: MF_Welch, MF_Parzen, and MF_Hanning. A square window is available by setting all matrix elements equal to 1.0 (MF_equC( MWin, htWin, lenWin, 1.0 ); ), but this is not recommended. htSpec and lenSpec must be integer powers of 2. MSpec has [htSpec+1][lenSpec+1] elements (!), and htX >= n*htSpec, lenX >= n*lenSpec, htWin = 2*htSpec, lenWin = 2*lenSpec. About special versions with the prefixes MFs_ and MFl_, consult chapter 4.8 of HANDBOOk.HTM.
Error handling | If either htSpec or lenSpec is not a power of 2, VF_FFT (on which MF_spectrum relies) complains "Size must be an integer power of 2" and the program is aborted. If MSpc overwrites MX or MWin, an error message "Vectors/matrices must not be identical" is generated and the program aborted.
See also | MF_FFT, MF_convolve, MF_autocorr, MF_xcorr, MF_filter, chapter 12

MFsym_sqrt | MDsym_sqrt | MEsym_sqrt
Function | Square root of a symmetric, positive definite matrix
Syntax C/C++ | #include <MFstd.h> int MFsym_sqrt( fMatrix MB, fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; function MFsym_sqrt( MB, MA:fMatrix; len:UInt ):IntBool;
Description | The square-root of a symmetric, positive definite matrix is calculated, so that MB * MB = MA is satisfied. Please note that non-symmetric matrices or matrices which are not positive definite may or may not have existing square-roots, too. The present algorithm, however, is restricted to the most simple case where a square-root always exists. It uses eigenvalues and eigenvectors and fails whenever a negative eigenvalue is encountered, indicating an input matrix which is not positive definite. In the latter case, an error message is displayed and the result is calculated with zero substituted for the negative eigenvalue. This result may still be useful, namely if the negative eigenvalue is very small. A return value of FALSE or 0 indicates success, whereas a non-zero return value indicates that the input matrix did not meet the condition of being symmetric and positive definite.
Return value | FALSE (0), if the matrix square-root could be calculated; otherwise TRUE (1)
See also | MF_eigenvalues, chapter 11

MF_store | MD_store | ME_store
MCF_store | MCD_store | MCE_store
Function | store a matrix in binary format into a stream
Syntax C/C++ | #include <MFstd.h> void MF_store( FILE *str, fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_store( var Stream:FILE; MA:fMatrix; ht, len:UInt );
Description | The matrix MA of ht*len elements is written to stream in binary format. The stream must be already open for binary write operations.
See also | MF_recall, chapter 14

MF_subM | MD_subM | ME_subM
MFs_subM | MDs_subM | MEs_subM
MCF_subM | MCD_subM | MCE_subM
Function | element-wise subtraction of two matrices
Syntax C/C++ | #include <MFstd.h> void MF_subM( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len ); void MFs_subM( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_subM( MC, MA, MB:fMatrix; ht, len:UInt ); procedure MFs_subM( MC, MA, MB:fMatrix; ht, len:UInt; C:Single );
Description | normal version: MCij = MAij - MBij scaled version: MCij = C * (MAij - MBij)
See also | MF_subMT, MF_addM, chapter 9

MF_subMT | MD_subMT | ME_subMT
MFs_subMT | MDs_subMT | MEs_subMT
MCF_subMT | MCD_subMT | MCE_subMT
Function | subtract the transpose of one matrix from another matrix
Syntax C/C++ | #include <MFstd.h> void MF_subMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len ); void MFs_subMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_subMT( MC, MA, MB:fMatrix; ht, len:UInt ); procedure MFs_subMT( MC, MA, MB:fMatrix; ht, len:UInt; C:Single );
Description | normal version: MCi,j = MAi,j - MBTj,i scaled version: MCi,j = C * (MAi,j - MBTj,i)
See also | MF_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
Function | reverse subtraction: subtract one matrix from the transpose of another
Syntax C/C++ | #include <MFstd.h> void MF_subrMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len ); void MFs_subrMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len, float C );
Pascal/Delphi | uses MFstd; procedure MF_subrMT( MC, MA, MB:fMatrix; ht, len:UInt ); procedure MFs_subrMT( MC, MA, MB:fMatrix; ht, len:UInt; C:Single );
Description | normal version: MCi,j = MBTj,i - MAi,j scaled version: MCi,j = C * (MBTj,i - MAi,j)
See also | MF_addM, MF_subMT, chapter 9

MF_submatrix | MD_submatrix | ME_submatrix
MCF_submatrix | MCD_submatrix | MCE_submatrix
Function | extract a submatrix from a (larger) matrix
Syntax C/C++ | #include <MFstd.h> void MF_submatrix( fMatrix MSub, unsigned subHt, unsigned subLen, fMatrix MSrce, unsigned srceHt, unsigned srceLen, unsigned firstRowInCol, unsigned sampInCol, unsigned firstColInRow, unsigned sampInRow );
Pascal/Delphi | uses MFstd; procedure MF_submatrix( MSub:fMatrix; subHt, subLen:UInt; MSrce:fMatrix; srceHt, srceLen:UInt; firstRowInCol, sampInCol, firstColInRow, sampInRow:UInt );
Description | MSubi, j = MSrcei*sampInCol+firstRowInCol, j*sampInRow+firstColInRow
See also | VF_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
Function | distribute the elements of a matrix to a submatrix of another (larger) matrix
Syntax C/C++ | #include <MFstd.h> void MF_submatrix_equM( fMatrix MDest, unsigned destHt, unsigned destLen, unsigned firstRowInCol, unsigned sampInCol, unsigned firstColInRow, unsigned sampInRow, fMatrix MSrce, unsigned srceHt, unsigned srceLen );
Pascal/Delphi | uses MFstd; procedure MF_submatrix_equM( MDest:fMatrix; destHt, destLen, firstRowInCol, sampInCol, firstColInRow, sampInRow:UInt; MSrce:fMatrix; srceHt, srceLen:UInt );
Description | MDesti*sampInCol+firstRowInCol, j*sampInRow+firstColInRow = MSrcei, j This function does the inverse of MF_submatrix
See also | VF_subvector, MF_Row_equV, MF_submatrix, chapter 5

MF_SVdecompose | MD_SVdecompose | ME_SVdecompose
Function | Singular Value Decomposition
Syntax C/C++ | #include <MFstd.h> int MF_SVdecompose( fMatrix MU, fMatrix MV, fVector W, fMatrix MA, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; function MF_SVdecompose( MU, MV:fMatrix; W:fVector; MA:fMatrix; htA, lenA:UInt ): IntBool;
Description | The matrix MA of dimensions [ht, len] is decomposed into a product MA = MU * MW * MVT, where MU has the dimensions [max(ht,len), len]. MW is a diagonal matrix with all elements positive or zero. Actually, only the diagonal of this matrix is stored in the vector W of size [len], MV, finally, is a square matrix [len, len]. Both MU and MV are orthogonal: MUT * MU = MVT * MV = (1). Due to these orthogonality relations, the solution of a linear system MA * X = B is straightforward, once MA has been singular-value decomposed: X = MV * W-1 * MUT (This equation must be evaluated from right to left.) As MU and MV are orthogonal, only W must explicitly be inverted. This, however, is again easy, as W is diagonal, and the inverse of a diagonal matrix consists of the inverse of the diagonal elements. This is the important point which makes SVD so useful, because it provides both a diagnose and a cure for singularities. If any element of W is very small compared to the largest element, this corresponds to a singularity (at least in the numerical sense, where dividing by extremely small numbers is almost as bad as dividing by zero). A singularity means that the underlying linear system is under-determined. This, in turn, means that one can arbitrarily choose one particular solution. Specifically, one may choose W-1ii = 0 for very small Wii, which is one of the rare cases where it makes sense to set the result of a division by (near-)zero to zero instead of infinity. This reduction of the dimension by "Singular Value editing" is the crucial point in all functions relying on SVD, like MF_SVsolve, MF_safeSolve), VF_linfit and others. The editing threshold is set by MF_SVDsetEdit. This function may not be called while the FPU is set to reduced accuracy, or else it might fail to achieve convergence. See V_setFPAccuracy. If you compare results of MF_SVdecompose with SVD-routines of other vendors, please note the following points: MF_SVdecompose itself does not perform a dimension reduction (replacement of small singular values by 0), but leaves this step to following functions or to manual inspection by the user. Singular values can be permutated, if the same permutation is also applied to the corresponding columns of both MU and MV. Sometimes, this property of SVD is exploited to bring the singular values into a certain (for example, into descending) order. As the price for this increased beauty is an increased work-load, MF_SVdecompose keeps the singular values in arbitrary order. The sign of a singular value may be exchanged if the corresponding column of MV is also multiplied by -1. MF_SVdecompose uses this property to make all non-vanishing singular values positive.
See also | MF_SVsolve, MF_safeSolve, MF_solveBySVD, chapter10

MF_SVDgetEdit | MD_SVDgetEdit | ME_SVDgetEdit
Function | retrieve current editing threshold for Singular Value backsubstitution
Syntax C/C++ | #include <MFstd.h> float MF_SVDgetEdit( void );
Pascal/Delphi | uses MFstd; function MF_SVDgetEdit: Single;
Description | This function returns the current Singular Value editing threshold. The SV editing threshold may be modified by MF_SVDsetEdit.
Return value | current SV editing threshold
See also | MF_SVdecompose, MF_SVsolve, chapter 10

MF_SVDsetEdit | MD_SVDsetEdit | ME_SVDsetEdit
Function | set the Singular Value editing threshold
Syntax C/C++ | #include <MFstd.h> void MF_SVDsetEdit( float Thresh );
Pascal/Delphi | uses MFstd; procedure MF_SVDsetEdit( Thresh:Single );
Description | As described in connection with MF_SVdecompose and MF_SVsolve, the crucial point in using functions which rely on Singular Value Decomposition is the Singular Value editing step. By default, the SV editing threshold is 4*FLT_EPSILON, 8*DBL_EPSILON, or 16*LDBL_EPSILON. You may change these values by calling MF_SVDsetEdit. To retrieve the current SV editing threshold, call MF_SVDgetEdit.
See also | MF_SVdecompose, MF_SVsolve, chapter 10

MF_SVsolve | MD_SVsolve | ME_SVsolve
Function | solve a system of linear equations, given its Singular Value decomposed form
Syntax C/C++ | #include <MFstd.h> void MF_SVsolve( fVector X, fMatrix MU, fMatrix MV, fVector W, fVector B, unsigned htU, unsigned lenU );
Pascal/Delphi | uses MFstd; procedure MF_SVsolve( X:fVector; MU, MV:fMatrix; W, B:fVector; htU, lenU:UInt );
Description | MF_SVsolve solves an SV-decomposed set of linear equations; sometimes this process is also called Singular Value Backsubstitution. In this function, at first W is edited such that elements smaller than a threshold are set to zero. Then, in the backsubstitution process, which involves divisions by the elements of W, any divisions by Wi = 0 are replaced by setting the result to 0. You can choose the editing threshold by calling MF_SVDsetEdit. If you prefer to inspect and edit W yourself before calling MF_SVsolve, you can call MF_SVDsetEdit with the argument 0.0, thereby switching off the automatic SV editing. The parameters lenU = lenA and htU = max( lenA, htA ) are the same as fed into MF_SVdecompose.
See also | MF_SVdecompose, MF_solveBySVD, chapter 10

MF_TmulM | MD_TmulM | ME_TmulM
MCF_TmulM | MCD_TmulM | MCE_TmulM
Function | multiply the transpose of one matrix by another matrix
Syntax C/C++ | #include <MFstd.h> void MF_TmulM( fMatrix MC, fMatrix MA, fMatrix MB, unsigned htA, unsigned lenA, unsigned lenB );
Pascal/Delphi | uses MFstd; procedure MF_TmulM( MC, MA, MB:fMatrix; htA, lenA, lenB:UInt );
Description | MC = MAT * MB htA, lenA, and lenB must be specified; the other dimensions are implicitly given as: htB = htA, lenC = lenB, htC = lenA. htA and lenA refer to the original, un-transposed input matrix.
See also | MF_mulM, MF_mulMT, chapter 9

MF_TmulMdia | MD_TmulMdia | ME_TmulMdia
MCF_TmulMdia | MCD_TmulMdia | MCE_TmulMdia
Function | multiply the transpose of a general matrix by a diagonal matrix
Syntax C/C++ | #include <MFstd.h> void MF_TmulMdia( fMatrix MC, fMatrix MA, fVector MBDia, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; procedure MF_TmulMdia( MC, MA:fMatrix; MBDia:fVector; htA, lenA:UInt );
Description | MC = MAT * MBDia htA and lenA must be specified. They refer to the original, un-transposed input matrix. Implicitly, sizB = htA.
See also | MFdia_mulM, chapter 9

MF_TmulMT | MD_TmulMT | ME_TmulMT
MCF_TmulMT | MCD_TmulMT | MCE_TmulMT
Function | multiply the transpose of one matrix by the transpose of another
Syntax C/C++ | #include <MFstd.h> void MF_TmulMT( fMatrix MC, fMatrix MA, fMatrix MB, unsigned htA, unsigned lenA, unsigned htB );
Pascal/Delphi | uses MFstd; procedure MF_TmulMT( MC, MA, MB:fMatrix; htA, lenA, htB:UInt );
Description | MC = MAT * MBT htA, lenA, and htB must be specified; the other dimensions are implicitly given as: lenB = htA, lenC = htB, htC = lenA. All dimensions refer to the original, un-transposed input matrices.
See also | MF_mulM, MF_TmulM, MF_mulMT, chapter 9

MF_TmulV | MD_TmulV | ME_TmulV
MCF_TmulV | MCD_TmulV | MCE_TmulV
Function | multiply the transpose of a matrix by a column vector
Syntax C/C++ | #include <MFstd.h> void MF_TmulV( fVector Y, fMatrix MA, fVector X, unsigned htA, unsigned lenA );
Pascal/Delphi | uses MFstd; procedure MF_TmulV( Y:fVector; MA:fMatrix; X:fVector; htA, lenA:UInt );
Description | Y = MAT * X The dimensions htA and lenA refer to the original (rather than the intermediate transposed) matrix MA; the dimensions of X and Y are implicitly given by the matrix dimensions: sizX = htA, sizY = lenA.
See also | MF_mulV, VF_mulM, chapter 9

MF_transpose | MD_transpose | ME_transpose
MCF_transpose | MCD_transpose | MCE_transpose
Function | transpose of a matrix
Syntax C/C++ | #include <MFstd.h> void MF_transpose( fMatrix MTr, fMatrix MA, unsigned htTr, unsigned lenTr );
Pascal/Delphi | uses MFstd; procedure MF_transpose( MTr, MA:fMatrix; htTr, lenTr:UInt );
Description | MTri,j = MAj,i The dimensions fed into this function, htTr and lenTr, refer to the transposed matrix rather than to the input matrix.
See also | MCF_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
Function | initialize the tridiagonal part of a matrix with the three vectors contained in a compacted tradiagonal matrix
Syntax C/C++ | #include <MFstd.h> void MF_Trd_equM( fMatrix MA, fMatrix MTrd, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Trd_equM( MA, MTrd:fMatrix; len:UInt );
Description | Row 0 of MTrd is copied into the first diagonal above the main diagonal of the square matrix MA. Row 1 of MTrd goes into the main diagonal of MA, and Row 2 of MTrd into the first diagonal below the main diagonal of MA. See chapter 1.2 for details about the storing of tridiagonal matrices.
See also | MF_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
Function | extract the tridiagonal part from a general matrix and store it into a compacted tridiagonal matrix
Syntax C/C++ | #include <MFstd.h> void MF_Trd_extract( fMatrix MTrd, fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Trd_extract( MTrd, MA:fMatrix; len:UInt );
Description | The first diagonal above the main diagonal of the square matrix MA is copied into Row 0 of MTrd. The main diagonal of MA goes into Row1 of MTrd, and the first diagonal below the main diagonal of MA is copied into Row 2 of MTrd. See chapter 1.2 for details about the storing of tridiagonal matrices.
See also | MF_Dia_extract, MF_Trd_equM, chapter 2

MF_UequL | MD_UequL | ME_UequL
MCF_UequL | MCD_UequL | MCE_UequL
Function | copy lower-diagonal elements into upper-diagonal by index-reflection, so as to get a symmetric matrix
Syntax C/C++ | #include <MFstd.h> void MF_UequL( fMatrix MA, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_UequL( MA:fMatrix; len:UInt );
Description | MAi,j = MAj,i, i < j
See also | MF_LequU, chapter 3

MF_Welch | MD_Welch | ME_Welch
Function | two-dimensional Welch window for use in spatial frequency analysis
Syntax C/C++ | #include <MFstd.h> void MF_Welch( fMatrix MA, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_Welch( MA:fMatrix; ht, len:UInt );
Description | MAi,j = (1 - ( (i - 0.5*(ht - 1)) / (0.5*(ht + 1)) )2) * (1 - ( (j - 0.5*(len - 1)) / (0.5*(len + 1)) )2)
See also | MF_Parzen, MF_Hanning, MF_spectrum

MF_write | MD_write | ME_write
MCF_write | MCD_write | MCE_write
Function | write a matrix in ASCII format into a stream
Syntax C/C++ | #include <MFstd.h> void MF_write( FILE *stream, fMatrix X, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; {Delphi version:} procedure MF_write( var Stream:TextFile; MA:fMatrix; ht, len:UInt ); {Turbo Pascal version:} procedure MF_write( var Stream:Text; MA:fMatrix; ht, len:UInt );
Description | The matrix MA with len columns and ht rows is written to stream in ASCII format. stream must already be open for write operations in text format. The number format and the separation between columns may be specified using MF_setWriteFormat (C/C++ only) and MF_setWriteSeparate, respectively. See these functions for details. Storing data in ASCII format is useful if the data have to be readable by human eyes, or if they are to be exported into other programs which are not able to read machine-format numbers. If avoidable, these functions should not be used for the storage of intermediate results that later have again to be read in. Instead, the function pairs of the MF_store / MF_recall family are recommended for the following reasons: conversion into ASCII format is slow, may lead to round-off errors, and requires much more disk memory than storage in machine format.
Error handling | none
See also | MF_setWriteFormat, MF_setWriteSeparate, MF_read, MF_store, MF_print, chapter 14

MF_xcorr | MD_xcorr | ME_xcorr
Function | spatial cross-correlation function
Syntax C/C++ | #include <MFstd.h> void MF_xcorr( fMatrix MC, fMatrix MA, fMatrix MB, unsigned ht, unsigned len );
Pascal/Delphi | uses MFstd; procedure MF_xcorr( MC, MA, MB:fMatrix; ht, len:UInt );
Description | The spatial cross-correlation function (SCCF) of MA and MB is calculated and stored in MC in wrap-around order in both dimensions: The row elements MCi,0 to MCi,len/2-1 contain the SCCF for zero and positive x lags. Beginning with the most negative lag in MCi,len/2+1, the elements up to MCi,len-1 contain the SCCF for negative lags. Since this function assumes MA and MB to be periodic, the SCCF for the most positive lag is identical to the SCCF for the most negative lag. This element is stored as MCi,len/2. Similarly, the column elements MC0,j to MClen/2-1,j contain the SCCF for zero and positive y lags. Beginning with the most negative lag in MClen/2+1,j, the elements up to MClen-1,j contain the SCCF for negative lags. To get the SCCF into normal order, you may call MF_Rows_rotate( MC, ht, len, len/2 ); MF_Cols_rotate( MC, ht, len, ht/2 ); After that, the zero point is at the position MCht/2,len/2. In case MA or MB are non-periodic, you should avoid end effects by the methods described in connection with MF_convolve. All three matrices involved have the same dimensions. Both ht and len must be integer powers of 2. About special versions with the prefixes MFl_ and MFs_, consult chapter 4.8 of HANDBOOK.HTM.
Error handling | If either len or ht is not a power of 2, VF_FFT (on which MF_xcorr is based) complains "Size must be an integer power of 2" and the program is aborted.
See also | MF_autocorr, chapter 12

MF_xyzAutoDensityMap | MD_xyzAutoDensityMap | ME_xyzAutoDensityMap
Function | draw an X-Y coordinate system and plot a color-density map for z = f( x, y ) into it
Syntax C/C++ | #include <Mgraph.h> void MF_xyzAutoDensityMap( fVector X, fVector Y, fMatrix MZ, unsigned ht, unsigned len, COLORREF mincolor, COLORREF maxcolor );
Pascal/Delphi | uses Mgraph; procedure MF_xyzAutoDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt; mincolor, maxcolor: COLORREF );
Description | A Cartesian coordinate system is drawn with automatic scaling of the axes and the matrix MZ is plotted as a color-density map against the vectors X and Y. Prior to calling MF_xyzAutoDensityMap, the plotting routines have to be initialized by V_initGraph (for DOS programs) or V_initPlot (DOS or Windows programs). The font of the axis tick labels is the actual text font. In DOS programs (Borland C++ or Pascal), it may be changed by calling settextstyle before calling MF_xyzAutoDensityMap. In Windows programs (both 16-bit and 32-bit), the font of the current device context is used. All MZ values will be translated into colors by linear interpolation between the parameters mincolor and maxcolor. DOS: The data type COLORREF is unsigned. See the Borland C++ or TurboPascal function setcolor for a description of the colors available in the various graphics modes. Windows: The data type COLORREF is unsigned long. The colors BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, BROWN, LIGHTGRAY, DARKGRAY, LIGHTBLUE, LIGHTGREEN, LIGHTCYAN, LIGHTRED, LIGHTMAGENTA, YELLOW, and WHITE are defined in <Vgraph.h> (or the unit Vgraph) by analogy with the COLORS defined for DOS in <graphics.h> (or the unit Graph) for the BGI routines. Thereby, portability between DOS and Windows programs is improved. For programs designed to run exclusively under Windows, it is nevertheless recommended to use fine-tuned colors defined by the RGB macro, instead of the predefined colors. If you wish to define the boudaries of the coordinate system differently, instead of relying on the automatic range detection and scaling, you may call first M_setDensityMapBounds or (for preserved automatic scaling, but with arbitrary x and y ranges) MF_findDensityMapBounds. Subsequently, call MF_xyzDataDensityMap instead of MF_xyzAutoDensityMap.
See also | MF_zAutoDensityMap, MF_xyzDataDensityMap, VF_xyAutoPlot, chapter 15

MF_xyzDataDensityMap | MD_xyzDataDensityMap | ME_xyzDataDensityMap
Function | plot a color density map z = f( x, y ) into an existing coordinate system with a previously defined color scale
Syntax C/C++ | #include <Mgraph.h> void MF_xyzDataDensityMap( fVector X, fVector Y, fMatrix MZ, unsigned ht, unsigned len );
Pascal/Delphi | uses Mgraph; procedure MF_xyzDataDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt );
Description | The 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 also | MF_zDataDensityMap, MF_xyzAutoDensityMap, chapter 15

MF_zAutoDensityMap | MD_zAutoDensityMap | ME_zAutoDensityMap
Function | plot a color density map of a matrix against the indices over its dimensions
Syntax C/C++ | #include <Mgraph.h> void MF_zAutoDensityMap( fMatrix MZ, unsigned ht, unsigned len, COLORREF mincolor, COLORREF maxcolor );
Pascal/Delphi | uses Mgraph; procedure MF_xyzDataDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt );
Description | This function is similar to MF_xyzAutoDensityMap, but here MZ is plotted against the indices of its dimensions instead of explicit X and Y values.
See also | MF_xyzAutoDensityMap, chapter 15

MF_zDataDensityMap | MD_zDataDensityMap | ME_zDataDensityMap
Function | plot a color-density map of a matrix into an existing coordinate system whose axes comprise the range of the indices of the matrix dimensions
Syntax C/C++ | #include <Mgraph.h> void MF_zDataDensityMap( fMatrix MZ, unsigned ht, unsigned len );
Pascal/Delphi | uses Mgraph; procedure MF_xyzDataDensityMap( X, Y:fVector; MZ:fMatrix; ht, len: UInt );
Description | This function is similar to MF_xyzDataDensityMap, but here MZ is plotted against the indices of its dimensions instead of explicit X and Y values.
See also | MF_xyzDataDensityMap, MF_xyzAutoDensityMap, chapter 15

MF_2DArrayToMatrix | MD_2DArrayToMatrix | ME_2DArrayToMatrix
MCF_2DArrayToMatrix | MCD_2DArrayToMatrix | MCE_2DArrayToMatrix
Function | convert 2D-array of Delphi 4 or higher into OptiVec matrix
Syntax C/C++ | N.A.
Pascal/Delphi | uses MFstd, VecLib; type fArray = array of Single; type f2DArray = array of fArray; procedure MF_2DArrayToMatrix( MF:fMatrix; DelphiArr:f2DArray; ht,len:UInt);
Description | This function is necessary only for Delphi 4 or higher. (Previous versions of Borland Pascal/Delphi did not support dynamically allocated matrices.) It converts two-dimensional Delphi arrays into OptiVec matrices. Note that, unlike static Pascal/Delphi matrices, the dynamic matrices of Delphi 4+ cannot directly be passed to OptiVec functions, but have to be converted first.
See also | MF_MatrixTo2DArray, chapter 1.4

Back to Table of Contents

#

E N D

Copyright for OptiVec software and documentation
© 1996-2001 OptiCode - Dr. Martin Sander Software Dev.
All rights reserved!