1 Introduction
    1.1 What is ALGLIB
    1.2 ALGLIB license
    1.3 Documentation license
    1.4 Reference Manual and User Guide
    1.5 Acknowledgements
2 Getting started with ALGLIB
    2.1 About ALGLIB for IronPython
    2.2 Compatibility
        2.2.1 Python interpreter
        2.2.2 Other
    2.3 Installing ALGLIB
    2.4 Using ALGLIB without installation
    2.5 Recompiling computational core
    2.6 Working with ALGLIB
        2.6.1 Datatypes
        2.6.2 Calling ALGLIB functions
        2.6.3 Handling errors
3 ALGLIB packages and subpackages
    3.1 AlglibMisc package
    3.2 DataAnalysis package
    3.3 DiffEquations package
    3.4 FastTransforms package
    3.5 Integration package
    3.6 Interpolation package
    3.7 LinAlg package
    3.8 Optimization package
    3.9 Solvers package
    3.10 SpecialFunctions package
    3.11 Statistics package

# valid matrices
v0 = [[]]
v1 = [[1],[2]]
v2 = [[1,2]]
v3 = [[1,2],[3,4]]

# invalid matrices
i0 = [[1],[1,2]]
i1 = ["string"]

import xalglib

def function1_grad(x, grad, param):
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

# L-BFGS optimizer with m=2 is created, one result is returned
s = xalglib.minlbfgscreate(2,[0,0,0])

# function with no output values is called
xalglib.minlbfgssetcond(state, 0, 0, 0, 10)

# some optimization code here 
xalglib.minlbfgsoptimize_g(state, function1_grad)

# and, finally, call to function with multiple outputs 
x, rep = xalglib.minlbfgsresults(state)

import xalglib

x  = [0,1,2,3]
y  = [1,5,3,9]
y2 = [1,5,3,9,0]


s = xalglib.spline1dbuildlinear(x, y, 4) # 'expert' interface is used, we passed the number of points
s = alglib.spline1dbuildlinear(x, y)    # 'friendly' interface - input size is
                                         # automatically determined

s = alglib.spline1dbuildlinear(x, y2, 4) # y2.length() is 5 (larger then len(x)), but it will work

s = alglib.spline1dbuildlinear(x, y2)    # it won't work because sizes of x and y2
                                          # are inconsistent

import xalglib

# 
# 'Friendly' interface: spdmatrixinverse() accepts and returns symmetric matrix
# 

# symmetric positive definite matrix
a = [[2,1],[1,2]]

# after this line A will contain [[0.66,-0.33],[-0.33,0.66]]
# which is symmetric too
a, info, rep = xalglib.spdmatrixinverse(a)

# you may try to pass nonsymmetric matrix
a = [[2,1],[0,2]]

# but exception will be thrown in such case
a, info, rep = xalglib.spdmatrixinverse(a)

import xalglib

# 
# 'Expert' interface, spdmatrixinverse()
# 

# only upper triangle is used; a[1][0] is initialized by NAN,
# but it can be arbitrary number
a = [[2,1],[float("nan"),2]]

# after this line A will contain [[0.66,-0.33],[NAN,0.66]]
# only upper triangle is modified
# 
# we use 'expert' form of spdmatrixinverse, which is spdmatrixinverse(a, n, isupper)
a, info, rep = xalglib.spdmatrixinverse(a, 2, true)

3 ALGLIB packages and subpackages

ablas module

cmatrixcopy function

#
# Copy
# 
# Input parameters:
#     M   -   number of rows
#     N   -   number of columns
#     A   -   source matrix, MxN submatrix is copied and transposed
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     B   -   destination matrix, must be large enough to store result
#     IB  -   submatrix offset (row index)
#     JB  -   submatrix offset (column index)
#

SYNTAX: b = xalglib.cmatrixcopy(m, n, a, ia, ja, b, ib, jb)

cmatrixgemm function

#
# This subroutine calculates C = alpha*op1(A)*op2(B) +beta*C where:
# * C is MxN general matrix
# * op1(A) is MxK matrix
# * op2(B) is KxN matrix
# * "op" may be identity transformation, transposition, conjugate transposition
# 
# Additional info:
# * cache-oblivious algorithm is used.
# * multiplication result replaces C. If Beta=0, C elements are not used in
#   calculations (not multiplied by zero - just not referenced)
# * if Alpha=0, A is not used (not multiplied by zero - just not referenced)
# * if both Beta and Alpha are zero, C is filled by zeros.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# IMPORTANT:
# 
# This function does NOT preallocate output matrix C, it MUST be preallocated
# by caller prior to calling this function. In case C does not have  enough
# space to store result, exception will be generated.
# 
# INPUT PARAMETERS
#     M       -   matrix size, M>0
#     N       -   matrix size, N>0
#     K       -   matrix size, K>0
#     Alpha   -   coefficient
#     A       -   matrix
#     IA      -   submatrix offset
#     JA      -   submatrix offset
#     OpTypeA -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#                 * 2 - conjugate transposition
#     B       -   matrix
#     IB      -   submatrix offset
#     JB      -   submatrix offset
#     OpTypeB -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#                 * 2 - conjugate transposition
#     Beta    -   coefficient
#     C       -   matrix (PREALLOCATED, large enough to store result)
#     IC      -   submatrix offset
#     JC      -   submatrix offset
# 
#   -- ALGLIB routine --
#      16.12.2009
#      Bochkanov Sergey
#

SYNTAX: c = xalglib.cmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)
SYNTAX: c = xalglib.smp_cmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)

Examples:   [1]  [2]  

cmatrixherk function

#
# This subroutine calculates  C=alpha*A*A^H+beta*C  or  C=alpha*A^H*A+beta*C
# where:
# * C is NxN Hermitian matrix given by its upper/lower triangle
# * A is NxK matrix when A*A^H is calculated, KxN matrix otherwise
# 
# Additional info:
# * cache-oblivious algorithm is used.
# * multiplication result replaces C. If Beta=0, C elements are not used in
#   calculations (not multiplied by zero - just not referenced)
# * if Alpha=0, A is not used (not multiplied by zero - just not referenced)
# * if both Beta and Alpha are zero, C is filled by zeros.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     N       -   matrix size, N>=0
#     K       -   matrix size, K>=0
#     Alpha   -   coefficient
#     A       -   matrix
#     IA      -   submatrix offset (row index)
#     JA      -   submatrix offset (column index)
#     OpTypeA -   multiplication type:
#                 * 0 - A*A^H is calculated
#                 * 2 - A^H*A is calculated
#     Beta    -   coefficient
#     C       -   preallocated input/output matrix
#     IC      -   submatrix offset (row index)
#     JC      -   submatrix offset (column index)
#     IsUpper -   whether upper or lower triangle of C is updated;
#                 this function updates only one half of C, leaving
#                 other half unchanged (not referenced at all).
# 
#   -- ALGLIB routine --
#      16.12.2009
#      Bochkanov Sergey
#

SYNTAX: c = xalglib.cmatrixherk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)
SYNTAX: c = xalglib.smp_cmatrixherk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)

Examples:   [1]  [2]  

cmatrixlefttrsm function

#
# This subroutine calculates op(A^-1)*X where:
# * X is MxN general matrix
# * A is MxM upper/lower triangular/unitriangular matrix
# * "op" may be identity transformation, transposition, conjugate transposition
# 
# Multiplication result replaces X.
# Cache-oblivious algorithm is used.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     N   -   matrix size, N>=0
#     M   -   matrix size, N>=0
#     A       -   matrix, actial matrix is stored in A[I1:I1+M-1,J1:J1+M-1]
#     I1      -   submatrix offset
#     J1      -   submatrix offset
#     IsUpper -   whether matrix is upper triangular
#     IsUnit  -   whether matrix is unitriangular
#     OpType  -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#                 * 2 - conjugate transposition
#     X   -   matrix, actial matrix is stored in X[I2:I2+M-1,J2:J2+N-1]
#     I2  -   submatrix offset
#     J2  -   submatrix offset
# 
#   -- ALGLIB routine --
#      15.12.2009
#      Bochkanov Sergey
#

SYNTAX: x = xalglib.cmatrixlefttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)
SYNTAX: x = xalglib.smp_cmatrixlefttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)

cmatrixmv function

#
# Matrix-vector product: y := op(A)*x
# 
# INPUT PARAMETERS:
#     M   -   number of rows of op(A)
#             M>=0
#     N   -   number of columns of op(A)
#             N>=0
#     A   -   target matrix
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     OpA -   operation type:
#             * OpA=0     =>  op(A) = A
#             * OpA=1     =>  op(A) = A^T
#             * OpA=2     =>  op(A) = A^H
#     X   -   input vector
#     IX  -   subvector offset
#     IY  -   subvector offset
#     Y   -   preallocated matrix, must be large enough to store result
# 
# OUTPUT PARAMETERS:
#     Y   -   vector which stores result
# 
# if M=0, then subroutine does nothing.
# if N=0, Y is filled by zeros.
# 
# 
#   -- ALGLIB routine --
# 
#      28.01.2010
#      Bochkanov Sergey
#

SYNTAX: y = xalglib.cmatrixmv(m, n, a, ia, ja, opa, x, ix, y, iy)

cmatrixrank1 function

#
# Rank-1 correction: A := A + u*v'
# 
# INPUT PARAMETERS:
#     M   -   number of rows
#     N   -   number of columns
#     A   -   target matrix, MxN submatrix is updated
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     U   -   vector #1
#     IU  -   subvector offset
#     V   -   vector #2
#     IV  -   subvector offset
#

SYNTAX: a, u, v = xalglib.cmatrixrank1(m, n, a, ia, ja, u, iu, v, iv)

cmatrixrighttrsm function

#
# This subroutine calculates X*op(A^-1) where:
# * X is MxN general matrix
# * A is NxN upper/lower triangular/unitriangular matrix
# * "op" may be identity transformation, transposition, conjugate transposition
# 
# Multiplication result replaces X.
# Cache-oblivious algorithm is used.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     N   -   matrix size, N>=0
#     M   -   matrix size, N>=0
#     A       -   matrix, actial matrix is stored in A[I1:I1+N-1,J1:J1+N-1]
#     I1      -   submatrix offset
#     J1      -   submatrix offset
#     IsUpper -   whether matrix is upper triangular
#     IsUnit  -   whether matrix is unitriangular
#     OpType  -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#                 * 2 - conjugate transposition
#     X   -   matrix, actial matrix is stored in X[I2:I2+M-1,J2:J2+N-1]
#     I2  -   submatrix offset
#     J2  -   submatrix offset
# 
#   -- ALGLIB routine --
#      15.12.2009
#      Bochkanov Sergey
#

SYNTAX: x = xalglib.cmatrixrighttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)
SYNTAX: x = xalglib.smp_cmatrixrighttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)

cmatrixsyrk function

#
# This subroutine is an older version of CMatrixHERK(), one with wrong  name
# (it is HErmitian update, not SYmmetric). It  is  left  here  for  backward
# compatibility.
# 
#   -- ALGLIB routine --
#      16.12.2009
#      Bochkanov Sergey
#

SYNTAX: c = xalglib.cmatrixsyrk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)
SYNTAX: c = xalglib.smp_cmatrixsyrk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)

cmatrixtranspose function

#
# Cache-oblivous complex "copy-and-transpose"
# 
# Input parameters:
#     M   -   number of rows
#     N   -   number of columns
#     A   -   source matrix, MxN submatrix is copied and transposed
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     B   -   destination matrix, must be large enough to store result
#     IB  -   submatrix offset (row index)
#     JB  -   submatrix offset (column index)
#

SYNTAX: b = xalglib.cmatrixtranspose(m, n, a, ia, ja, b, ib, jb)

rmatrixcopy function

#
# Copy
# 
# Input parameters:
#     M   -   number of rows
#     N   -   number of columns
#     A   -   source matrix, MxN submatrix is copied and transposed
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     B   -   destination matrix, must be large enough to store result
#     IB  -   submatrix offset (row index)
#     JB  -   submatrix offset (column index)
#

SYNTAX: b = xalglib.rmatrixcopy(m, n, a, ia, ja, b, ib, jb)

rmatrixenforcesymmetricity function

#
# This code enforces symmetricy of the matrix by copying Upper part to lower
# one (or vice versa).
# 
# INPUT PARAMETERS:
#     A   -   matrix
#     N   -   number of rows/columns
#     IsUpper - whether we want to copy upper triangle to lower one (True)
#             or vice versa (False).
#

SYNTAX: a = xalglib.rmatrixenforcesymmetricity(a, n, isupper)

rmatrixgemm function

#
# This subroutine calculates C = alpha*op1(A)*op2(B) +beta*C where:
# * C is MxN general matrix
# * op1(A) is MxK matrix
# * op2(B) is KxN matrix
# * "op" may be identity transformation, transposition
# 
# Additional info:
# * cache-oblivious algorithm is used.
# * multiplication result replaces C. If Beta=0, C elements are not used in
#   calculations (not multiplied by zero - just not referenced)
# * if Alpha=0, A is not used (not multiplied by zero - just not referenced)
# * if both Beta and Alpha are zero, C is filled by zeros.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# IMPORTANT:
# 
# This function does NOT preallocate output matrix C, it MUST be preallocated
# by caller prior to calling this function. In case C does not have  enough
# space to store result, exception will be generated.
# 
# INPUT PARAMETERS
#     M       -   matrix size, M>0
#     N       -   matrix size, N>0
#     K       -   matrix size, K>0
#     Alpha   -   coefficient
#     A       -   matrix
#     IA      -   submatrix offset
#     JA      -   submatrix offset
#     OpTypeA -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#     B       -   matrix
#     IB      -   submatrix offset
#     JB      -   submatrix offset
#     OpTypeB -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#     Beta    -   coefficient
#     C       -   PREALLOCATED output matrix, large enough to store result
#     IC      -   submatrix offset
#     JC      -   submatrix offset
# 
#   -- ALGLIB routine --
#      2009-2013
#      Bochkanov Sergey
#

SYNTAX: c = xalglib.rmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)
SYNTAX: c = xalglib.smp_rmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)

Examples:   [1]  [2]  

rmatrixlefttrsm function

#
# This subroutine calculates op(A^-1)*X where:
# * X is MxN general matrix
# * A is MxM upper/lower triangular/unitriangular matrix
# * "op" may be identity transformation, transposition
# 
# Multiplication result replaces X.
# Cache-oblivious algorithm is used.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     N   -   matrix size, N>=0
#     M   -   matrix size, N>=0
#     A       -   matrix, actial matrix is stored in A[I1:I1+M-1,J1:J1+M-1]
#     I1      -   submatrix offset
#     J1      -   submatrix offset
#     IsUpper -   whether matrix is upper triangular
#     IsUnit  -   whether matrix is unitriangular
#     OpType  -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#     X   -   matrix, actial matrix is stored in X[I2:I2+M-1,J2:J2+N-1]
#     I2  -   submatrix offset
#     J2  -   submatrix offset
# 
#   -- ALGLIB routine --
#      15.12.2009
#      Bochkanov Sergey
#

SYNTAX: x = xalglib.rmatrixlefttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)
SYNTAX: x = xalglib.smp_rmatrixlefttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)

rmatrixmv function

#
# Matrix-vector product: y := op(A)*x
# 
# INPUT PARAMETERS:
#     M   -   number of rows of op(A)
#     N   -   number of columns of op(A)
#     A   -   target matrix
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     OpA -   operation type:
#             * OpA=0     =>  op(A) = A
#             * OpA=1     =>  op(A) = A^T
#     X   -   input vector
#     IX  -   subvector offset
#     IY  -   subvector offset
#     Y   -   preallocated matrix, must be large enough to store result
# 
# OUTPUT PARAMETERS:
#     Y   -   vector which stores result
# 
# if M=0, then subroutine does nothing.
# if N=0, Y is filled by zeros.
# 
# 
#   -- ALGLIB routine --
# 
#      28.01.2010
#      Bochkanov Sergey
#

SYNTAX: y = xalglib.rmatrixmv(m, n, a, ia, ja, opa, x, ix, y, iy)

rmatrixrank1 function

#
# Rank-1 correction: A := A + u*v'
# 
# INPUT PARAMETERS:
#     M   -   number of rows
#     N   -   number of columns
#     A   -   target matrix, MxN submatrix is updated
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     U   -   vector #1
#     IU  -   subvector offset
#     V   -   vector #2
#     IV  -   subvector offset
#

SYNTAX: a, u, v = xalglib.rmatrixrank1(m, n, a, ia, ja, u, iu, v, iv)

rmatrixrighttrsm function

#
# This subroutine calculates X*op(A^-1) where:
# * X is MxN general matrix
# * A is NxN upper/lower triangular/unitriangular matrix
# * "op" may be identity transformation, transposition
# 
# Multiplication result replaces X.
# Cache-oblivious algorithm is used.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     N   -   matrix size, N>=0
#     M   -   matrix size, N>=0
#     A       -   matrix, actial matrix is stored in A[I1:I1+N-1,J1:J1+N-1]
#     I1      -   submatrix offset
#     J1      -   submatrix offset
#     IsUpper -   whether matrix is upper triangular
#     IsUnit  -   whether matrix is unitriangular
#     OpType  -   transformation type:
#                 * 0 - no transformation
#                 * 1 - transposition
#     X   -   matrix, actial matrix is stored in X[I2:I2+M-1,J2:J2+N-1]
#     I2  -   submatrix offset
#     J2  -   submatrix offset
# 
#   -- ALGLIB routine --
#      15.12.2009
#      Bochkanov Sergey
#

SYNTAX: x = xalglib.rmatrixrighttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)
SYNTAX: x = xalglib.smp_rmatrixrighttrsm(m, n, a, i1, j1, isupper, isunit, optype, x, i2, j2)

rmatrixsyrk function

#
# This subroutine calculates  C=alpha*A*A^T+beta*C  or  C=alpha*A^T*A+beta*C
# where:
# * C is NxN symmetric matrix given by its upper/lower triangle
# * A is NxK matrix when A*A^T is calculated, KxN matrix otherwise
# 
# Additional info:
# * cache-oblivious algorithm is used.
# * multiplication result replaces C. If Beta=0, C elements are not used in
#   calculations (not multiplied by zero - just not referenced)
# * if Alpha=0, A is not used (not multiplied by zero - just not referenced)
# * if both Beta and Alpha are zero, C is filled by zeros.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  Because  starting/stopping  worker  thread always
#   ! involves some overhead, parallelism starts to be  profitable  for  N's
#   ! larger than 128.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     N       -   matrix size, N>=0
#     K       -   matrix size, K>=0
#     Alpha   -   coefficient
#     A       -   matrix
#     IA      -   submatrix offset (row index)
#     JA      -   submatrix offset (column index)
#     OpTypeA -   multiplication type:
#                 * 0 - A*A^T is calculated
#                 * 2 - A^T*A is calculated
#     Beta    -   coefficient
#     C       -   preallocated input/output matrix
#     IC      -   submatrix offset (row index)
#     JC      -   submatrix offset (column index)
#     IsUpper -   whether C is upper triangular or lower triangular
# 
#   -- ALGLIB routine --
#      16.12.2009
#      Bochkanov Sergey
#

SYNTAX: c = xalglib.rmatrixsyrk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)
SYNTAX: c = xalglib.smp_rmatrixsyrk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)

Examples:   [1]  [2]  

rmatrixtranspose function

#
# Cache-oblivous real "copy-and-transpose"
# 
# Input parameters:
#     M   -   number of rows
#     N   -   number of columns
#     A   -   source matrix, MxN submatrix is copied and transposed
#     IA  -   submatrix offset (row index)
#     JA  -   submatrix offset (column index)
#     B   -   destination matrix, must be large enough to store result
#     IB  -   submatrix offset (row index)
#     JB  -   submatrix offset (column index)
#

SYNTAX: b = xalglib.rmatrixtranspose(m, n, a, ia, ja, b, ib, jb)

ablas_d_gemm example

import xalglib



a = [[2,1],[1,3]]
b = [[2,1],[0,1]]
c = [[0,0],[0,0]]

#
# rmatrixgemm() function allows us to calculate matrix product C:=A*B or
# to perform more general operation, C:=alpha*op1(A)*op2(B)+beta*C,
# where A, B, C are rectangular matrices, op(X) can be X or X^T,
# alpha and beta are scalars.
#
# This function:
# * can apply transposition and/or multiplication by scalar to operands
# * can use arbitrary part of matrices A/B (given by submatrix offset)
# * can store result into arbitrary part of C
# * for performance reasons requires C to be preallocated
#
# Parameters of this function are:
# * M, N, K            -   sizes of op1(A) (which is MxK), op2(B) (which
#                          is KxN) and C (which is MxN)
# * Alpha              -   coefficient before A*B
# * A, IA, JA          -   matrix A and offset of the submatrix
# * OpTypeA            -   transformation type:
#                          0 - no transformation
#                          1 - transposition
# * B, IB, JB          -   matrix B and offset of the submatrix
# * OpTypeB            -   transformation type:
#                          0 - no transformation
#                          1 - transposition
# * Beta               -   coefficient before C
# * C, IC, JC          -   preallocated matrix C and offset of the submatrix
#
# Below we perform simple product C:=A*B (alpha=1, beta=0)
#
# IMPORTANT: this function works with preallocated C, which must be large
#            enough to store multiplication result.
#
m = 2
n = 2
k = 2
alpha = 1.0
ia = 0
ja = 0
optypea = 0
ib = 0
jb = 0
optypeb = 0
beta = 0.0
ic = 0
jc = 0
c = xalglib.rmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)
print(c) # expected [[4,3],[2,4]]

#
# Now we try to apply some simple transformation to operands: C:=A*B^T
#
optypeb = 1
c = xalglib.rmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)
print(c) # expected [[5,1],[5,3]]

ablas_d_syrk example

import xalglib



#
# rmatrixsyrk() function allows us to calculate symmetric rank-K update
# C := beta*C + alpha*A'*A, where C is square N*N matrix, A is square K*N
# matrix, alpha and beta are scalars. It is also possible to update by
# adding A*A' instead of A'*A.
#
# Parameters of this function are:
# * N, K       -   matrix size
# * Alpha      -   coefficient before A
# * A, IA, JA  -   matrix and submatrix offsets
# * OpTypeA    -   multiplication type:
#                  * 0 - A*A^T is calculated
#                  * 2 - A^T*A is calculated
# * Beta       -   coefficient before C
# * C, IC, JC  -   preallocated input/output matrix and submatrix offsets
# * IsUpper    -   whether upper or lower triangle of C is updated;
#                  this function updates only one half of C, leaving
#                  other half unchanged (not referenced at all).
#
# Below we will show how to calculate simple product C:=A'*A
#
# NOTE: beta=0 and we do not use previous value of C, but still it
#       MUST be preallocated.
#
n = 2
k = 1
alpha = 1.0
ia = 0
ja = 0
optypea = 2
beta = 0.0
ic = 0
jc = 0
isupper = True
a = [[1,2]]

# preallocate space to store result
c = [[0,0],[0,0]]

# calculate product, store result into upper part of c
c = xalglib.rmatrixsyrk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)

# output result.
# IMPORTANT: lower triangle of C was NOT updated!
print(c) # expected [[1,2],[0,4]]

ablas_smp_gemm example

import xalglib



#
# In this example we assume that you already know how to work with
# rmatrixgemm() function. Below we concentrate on its multithreading
# capabilities.
#
# SMP edition of ALGLIB includes smp_rmatrixgemm() - multithreaded
# version of rmatrixgemm() function. In the basic edition of ALGLIB
# (GPL edition or commercial version without SMP support) this function
# just calls single-threaded stub. So, you may call this function from
# ANY edition of ALGLIB, but only in SMP edition it will work in really
# multithreaded mode.
#
# In order to use multithreading, you have to:
# 1) Install SMP edition of ALGLIB.
# 2) This step is specific for C++ users: you should activate OS-specific
#    capabilities of ALGLIB by defining AE_OS=AE_POSIX (for *nix systems)
#    or AE_OS=AE_WINDOWS (for Windows systems).
#    C# users do not have to perform this step because C# programs are
#    portable across different systems without OS-specific tuning.
# 3) Allow ALGLIB to know about number of worker threads to use:
#    a) autodetection (C++, C#):
#          ALGLIB will automatically determine number of CPU cores and
#          (by default) will use all cores except for one. Say, on 4-core
#          system it will use three cores - unless you manually told it
#          to use more or less. It will keep your system responsive during
#          lengthy computations.
#          Such behavior may be changed with setnworkers() call:
#          * alglib::setnworkers(0)  = use all cores
#          * alglib::setnworkers(-1) = leave one core unused
#          * alglib::setnworkers(-2) = leave two cores unused
#          * alglib::setnworkers(+2) = use 2 cores (even if you have more)
#    b) manual specification (C++, C#):
#          You may want to specify maximum number of worker threads during
#          compile time by means of preprocessor definition AE_NWORKERS.
#          For C++ it will be "AE_NWORKERS=X" where X can be any positive number.
#          For C# it is "AE_NWORKERSX", where X should be replaced by number of
#          workers (AE_NWORKERS2, AE_NWORKERS3, AE_NWORKERS4, ...).
#          You can add this definition to compiler command line or change
#          corresponding project settings in your IDE.
#
# After you installed and configured SMP edition of ALGLIB, you may choose
# between serial and multithreaded versions of SMP-capable functions:
# * serial version works as usual, in the context of the calling thread
# * multithreaded version (with "smp_" prefix) creates (or wakes up) worker
#   threads, inserts task in the worker queue, and waits for completion of
#   the task. All processing is done in context of worker thread(s).
#
# NOTE: because starting/stopping worker threads costs thousands of CPU cycles,
#       you should not use multithreading for lightweight computational problems.
#
# NOTE: some old POSIX-compatible operating systems do not support
#       sysconf(_SC_NPROCESSORS_ONLN) system call which is required in order
#       to automatically determine number of active cores. On these systems
#       you should specify number of cores manually at compile time.
#       Without it ALGLIB will run in single-threaded mode.
#
# Now, back to our example. In this example we will show you:
# * how to call SMP version of rmatrixgemm(). Because we work with tiny 2x2
#   matrices, we won't expect to see ANY speedup from using multithreading.
#   The only purpose of this demo is to show how to call SMP functions.
# * how to modify number of worker threads used by ALGLIB
#
a = [[2,1],[1,3]]
b = [[2,1],[0,1]]
c = [[0,0],[0,0]]
m = 2
n = 2
k = 2
alpha = 1.0
ia = 0
ja = 0
optypea = 0
ib = 0
jb = 0
optypeb = 0
beta = 0.0
ic = 0
jc = 0

# serial code
c = [[0,0],[0,0]]
c = xalglib.rmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)

# SMP code with default number of worker threads
c = [[0,0],[0,0]]
c = xalglib.smp_rmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)
print(c) # expected [[4,3],[2,4]]

# override number of worker threads - use two cores
xalglib.setnworkers(+2);
c = [[0,0],[0,0]]
c = xalglib.smp_rmatrixgemm(m, n, k, alpha, a, ia, ja, optypea, b, ib, jb, optypeb, beta, c, ic, jc)
print(c) # expected [[4,3],[2,4]]

ablas_smp_syrk example

import xalglib



#
# In this example we assume that you already know how to work with
# rmatrixsyrk() function. Below we concentrate on its multithreading
# capabilities.
#
# SMP edition of ALGLIB includes smp_rmatrixsyrk() - multithreaded
# version of rmatrixsyrk() function. In the basic edition of ALGLIB
# (GPL edition or commercial version without SMP support) this function
# just calls single-threaded stub. So, you may call this function from
# ANY edition of ALGLIB, but only in SMP edition it will work in really
# multithreaded mode.
#
# In order to use multithreading, you have to:
# 1) Install SMP edition of ALGLIB.
# 2) This step is specific for C++ users: you should activate OS-specific
#    capabilities of ALGLIB by defining AE_OS=AE_POSIX (for *nix systems)
#    or AE_OS=AE_WINDOWS (for Windows systems).
#    C# users do not have to perform this step because C# programs are
#    portable across different systems without OS-specific tuning.
# 3) Allow ALGLIB to know about number of worker threads to use:
#    a) autodetection (C++, C#):
#          ALGLIB will automatically determine number of CPU cores and
#          (by default) will use all cores except for one. Say, on 4-core
#          system it will use three cores - unless you manually told it
#          to use more or less. It will keep your system responsive during
#          lengthy computations.
#          Such behavior may be changed with setnworkers() call:
#          * alglib::setnworkers(0)  = use all cores
#          * alglib::setnworkers(-1) = leave one core unused
#          * alglib::setnworkers(-2) = leave two cores unused
#          * alglib::setnworkers(+2) = use 2 cores (even if you have more)
#    b) manual specification (C++, C#):
#          You may want to specify maximum number of worker threads during
#          compile time by means of preprocessor definition AE_NWORKERS.
#          For C++ it will be "AE_NWORKERS=X" where X can be any positive number.
#          For C# it is "AE_NWORKERSX", where X should be replaced by number of
#          workers (AE_NWORKERS2, AE_NWORKERS3, AE_NWORKERS4, ...).
#          You can add this definition to compiler command line or change
#          corresponding project settings in your IDE.
#
# After you installed and configured SMP edition of ALGLIB, you may choose
# between serial and multithreaded versions of SMP-capable functions:
# * serial version works as usual, in the context of the calling thread
# * multithreaded version (with "smp_" prefix) creates (or wakes up) worker
#   threads, inserts task in the worker queue, and waits for completion of
#   the task. All processing is done in context of worker thread(s).
#
# NOTE: because starting/stopping worker threads costs thousands of CPU cycles,
#       you should not use multithreading for lightweight computational problems.
#
# NOTE: some old POSIX-compatible operating systems do not support
#       sysconf(_SC_NPROCESSORS_ONLN) system call which is required in order
#       to automatically determine number of active cores. On these systems
#       you should specify number of cores manually at compile time.
#       Without it ALGLIB will run in single-threaded mode.
#
# Now, back to our example. In this example we will show you:
# * how to call SMP version of rmatrixsyrk(). Because we work with tiny 2x2
#   matrices, we won't expect to see ANY speedup from using multithreading.
#   The only purpose of this demo is to show how to call SMP functions.
# * how to modify number of worker threads used by ALGLIB
#
n = 2
k = 1
alpha = 1.0
ia = 0
ja = 0
optypea = 2
beta = 0.0
ic = 0
jc = 0
isupper = True
a = [[1,2]]
c = [[]]

#
# Default number of worker threads.
# Preallocate space to store result, call multithreaded version, test.
#
# NOTE: this function updates only one triangular part of C. In our
#       example we choose to update upper triangle.
#
c = [[0,0],[0,0]]
c = xalglib.smp_rmatrixsyrk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)
print(c) # expected [[1,2],[0,4]]

#
# Override default number of worker threads (set to 2).
# Preallocate space to store result, call multithreaded version, test.
#
# NOTE: this function updates only one triangular part of C. In our
#       example we choose to update upper triangle.
#
xalglib.setnworkers(+2);
c = [[0,0],[0,0]]
c = xalglib.smp_rmatrixsyrk(n, k, alpha, a, ia, ja, optypea, beta, c, ic, jc, isupper)
print(c) # expected [[1,2],[0,4]]

airyf module

airy function

#
# Airy function
# 
# Solution of the differential equation
# 
# y"(x) = xy.
# 
# The function returns the two independent solutions Ai, Bi
# and their first derivatives Ai'(x), Bi'(x).
# 
# Evaluation is by power series summation for small x,
# by rational minimax approximations for large x.
# 
# 
# 
# ACCURACY:
# Error criterion is absolute when function <= 1, relative
# when function > 1, except * denotes relative error criterion.
# For large negative x, the absolute error increases as x^1.5.
# For large positive x, the relative error increases as x^1.5.
# 
# Arithmetic  domain   function  # trials      peak         rms
# IEEE        -10, 0     Ai        10000       1.6e-15     2.7e-16
# IEEE          0, 10    Ai        10000       2.3e-14*    1.8e-15*
# IEEE        -10, 0     Ai'       10000       4.6e-15     7.6e-16
# IEEE          0, 10    Ai'       10000       1.8e-14*    1.5e-15*
# IEEE        -10, 10    Bi        30000       4.2e-15     5.3e-16
# IEEE        -10, 10    Bi'       30000       4.9e-15     7.3e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: ai, aip, bi, bip = xalglib.airy(x)

autogk module

autogkreport class

#
# Integration report:
# * TerminationType = completetion code:
#     * -5    non-convergence of Gauss-Kronrod nodes
#             calculation subroutine.
#     * -1    incorrect parameters were specified
#     *  1    OK
# * Rep.NFEV countains number of function calculations
# * Rep.NIntervals contains number of intervals [a,b]
#   was partitioned into.
#

class autogkreport(object):
    ...

autogkstate class

#
# This structure stores state of the integration algorithm.
# 
# Although this class has public fields,  they are not intended for external
# use. You should use ALGLIB functions to work with this class:
# * autogksmooth()/AutoGKSmoothW()/... to create objects
# * autogkintegrate() to begin integration
# * autogkresults() to get results
#

class autogkstate(object):
    ...

autogkintegrate function

#
# This function is used to launcn iterations of ODE solver
# 
# It accepts following parameters:
#     diff    -   callback which calculates dy/dx for given y and x
#     obj     -   optional object which is passed to diff; can be NULL
# 
# 
#   -- ALGLIB --
#      Copyright 07.05.2009 by Bochkanov Sergey
#

SYNTAX: xalglib.autogkintegrate(state, func, param = None)

Examples:   [1]  

autogkresults function

#
# Adaptive integration results
# 
# Called after AutoGKIteration returned False.
# 
# Input parameters:
#     State   -   algorithm state (used by AutoGKIteration).
# 
# Output parameters:
#     V       -   integral(f(x)dx,a,b)
#     Rep     -   optimization report (see AutoGKReport description)
# 
#   -- ALGLIB --
#      Copyright 14.11.2007 by Bochkanov Sergey
#

SYNTAX: v, rep = xalglib.autogkresults(state)

Examples:   [1]  

autogksingular function

#
# Integration on a finite interval [A,B].
# Integrand have integrable singularities at A/B.
# 
# F(X) must diverge as "(x-A)^alpha" at A, as "(B-x)^beta" at B,  with known
# alpha/beta (alpha>-1, beta>-1).  If alpha/beta  are  not known,  estimates
# from below can be used (but these estimates should be greater than -1 too).
# 
# One  of  alpha/beta variables (or even both alpha/beta) may be equal to 0,
# which means than function F(x) is non-singular at A/B. Anyway (singular at
# bounds or not), function F(x) is supposed to be continuous on (A,B).
# 
# Fast-convergent algorithm based on a Gauss-Kronrod formula is used. Result
# is calculated with accuracy close to the machine precision.
# 
# INPUT PARAMETERS:
#     A, B    -   interval boundaries (A<B, A=B or A>B)
#     Alpha   -   power-law coefficient of the F(x) at A,
#                 Alpha>-1
#     Beta    -   power-law coefficient of the F(x) at B,
#                 Beta>-1
# 
# OUTPUT PARAMETERS
#     State   -   structure which stores algorithm state
# 
# SEE ALSO
#     AutoGKSmooth, AutoGKSmoothW, AutoGKResults.
# 
# 
#   -- ALGLIB --
#      Copyright 06.05.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.autogksingular(a, b, alpha, beta)

autogksmooth function

#
# Integration of a smooth function F(x) on a finite interval [a,b].
# 
# Fast-convergent algorithm based on a Gauss-Kronrod formula is used. Result
# is calculated with accuracy close to the machine precision.
# 
# Algorithm works well only with smooth integrands.  It  may  be  used  with
# continuous non-smooth integrands, but with  less  performance.
# 
# It should never be used with integrands which have integrable singularities
# at lower or upper limits - algorithm may crash. Use AutoGKSingular in such
# cases.
# 
# INPUT PARAMETERS:
#     A, B    -   interval boundaries (A<B, A=B or A>B)
# 
# OUTPUT PARAMETERS
#     State   -   structure which stores algorithm state
# 
# SEE ALSO
#     AutoGKSmoothW, AutoGKSingular, AutoGKResults.
# 
# 
#   -- ALGLIB --
#      Copyright 06.05.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.autogksmooth(a, b)

Examples:   [1]  

autogksmoothw function

#
# Integration of a smooth function F(x) on a finite interval [a,b].
# 
# This subroutine is same as AutoGKSmooth(), but it guarantees that interval
# [a,b] is partitioned into subintervals which have width at most XWidth.
# 
# Subroutine  can  be  used  when  integrating nearly-constant function with
# narrow "bumps" (about XWidth wide). If "bumps" are too narrow, AutoGKSmooth
# subroutine can overlook them.
# 
# INPUT PARAMETERS:
#     A, B    -   interval boundaries (A<B, A=B or A>B)
# 
# OUTPUT PARAMETERS
#     State   -   structure which stores algorithm state
# 
# SEE ALSO
#     AutoGKSmooth, AutoGKSingular, AutoGKResults.
# 
# 
#   -- ALGLIB --
#      Copyright 06.05.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.autogksmoothw(a, b, xwidth)

autogk_d1 example

import xalglib

def int_function_1_func(x, xminusa, bminusx, param):
    #
    # this callback calculates f(x)=exp(x)
    #
    return math.exp(x)

#
# This example demonstrates integration of f=exp(x) on [0,1]:
# * first, autogkstate is initialized
# * then we call integration function
# * and finally we obtain results with autogkresults() call
#
a = 0
b = 1

s = xalglib.autogksmooth(a, b)
xalglib.autogkintegrate(s, int_function_1_func);
v, rep = xalglib.autogkresults(s)

print(v) # expected 1.7182

basestat module

cov2 function

#
# 2-sample covariance
# 
# Input parameters:
#     X       -   sample 1 (array indexes: [0..N-1])
#     Y       -   sample 2 (array indexes: [0..N-1])
#     N       -   N>=0, sample size:
#                 * if given, only N leading elements of X/Y are processed
#                 * if not given, automatically determined from input sizes
# 
# Result:
#     covariance (zero for N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: result = xalglib.cov2(x, y, n)
SYNTAX: result = xalglib.cov2(x, y)

Examples:   [1]  

covm function

#
# Covariance matrix
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! with covariance matrices smaller than 128*128.
# 
# INPUT PARAMETERS:
#     X   -   array[N,M], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     N   -   N>=0, number of observations:
#             * if given, only leading N rows of X are used
#             * if not given, automatically determined from input size
#     M   -   M>0, number of variables:
#             * if given, only leading M columns of X are used
#             * if not given, automatically determined from input size
# 
# OUTPUT PARAMETERS:
#     C   -   array[M,M], covariance matrix (zero if N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: c = xalglib.covm(x, n, m)
SYNTAX: c = xalglib.covm(x)
SYNTAX: c = xalglib.smp_covm(x, n, m)
SYNTAX: c = xalglib.smp_covm(x)

Examples:   [1]  

covm2 function

#
# Cross-covariance matrix
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! with covariance matrices smaller than 128*128.
# 
# INPUT PARAMETERS:
#     X   -   array[N,M1], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     Y   -   array[N,M2], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     N   -   N>=0, number of observations:
#             * if given, only leading N rows of X/Y are used
#             * if not given, automatically determined from input sizes
#     M1  -   M1>0, number of variables in X:
#             * if given, only leading M1 columns of X are used
#             * if not given, automatically determined from input size
#     M2  -   M2>0, number of variables in Y:
#             * if given, only leading M1 columns of X are used
#             * if not given, automatically determined from input size
# 
# OUTPUT PARAMETERS:
#     C   -   array[M1,M2], cross-covariance matrix (zero if N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: c = xalglib.covm2(x, y, n, m1, m2)
SYNTAX: c = xalglib.covm2(x, y)
SYNTAX: c = xalglib.smp_covm2(x, y, n, m1, m2)
SYNTAX: c = xalglib.smp_covm2(x, y)

Examples:   [1]  

pearsoncorr2 function

#
# Pearson product-moment correlation coefficient
# 
# Input parameters:
#     X       -   sample 1 (array indexes: [0..N-1])
#     Y       -   sample 2 (array indexes: [0..N-1])
#     N       -   N>=0, sample size:
#                 * if given, only N leading elements of X/Y are processed
#                 * if not given, automatically determined from input sizes
# 
# Result:
#     Pearson product-moment correlation coefficient
#     (zero for N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: result = xalglib.pearsoncorr2(x, y, n)
SYNTAX: result = xalglib.pearsoncorr2(x, y)

Examples:   [1]  

pearsoncorrelation function

#
# Obsolete function, we recommend to use PearsonCorr2().
# 
#   -- ALGLIB --
#      Copyright 09.04.2007 by Bochkanov Sergey
#

SYNTAX: result = xalglib.pearsoncorrelation(x, y, n)

pearsoncorrm function

#
# Pearson product-moment correlation matrix
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! with correlation matrices smaller than 128*128.
# 
# INPUT PARAMETERS:
#     X   -   array[N,M], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     N   -   N>=0, number of observations:
#             * if given, only leading N rows of X are used
#             * if not given, automatically determined from input size
#     M   -   M>0, number of variables:
#             * if given, only leading M columns of X are used
#             * if not given, automatically determined from input size
# 
# OUTPUT PARAMETERS:
#     C   -   array[M,M], correlation matrix (zero if N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: c = xalglib.pearsoncorrm(x, n, m)
SYNTAX: c = xalglib.pearsoncorrm(x)
SYNTAX: c = xalglib.smp_pearsoncorrm(x, n, m)
SYNTAX: c = xalglib.smp_pearsoncorrm(x)

Examples:   [1]  

pearsoncorrm2 function

#
# Pearson product-moment cross-correlation matrix
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! with correlation matrices smaller than 128*128.
# 
# INPUT PARAMETERS:
#     X   -   array[N,M1], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     Y   -   array[N,M2], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     N   -   N>=0, number of observations:
#             * if given, only leading N rows of X/Y are used
#             * if not given, automatically determined from input sizes
#     M1  -   M1>0, number of variables in X:
#             * if given, only leading M1 columns of X are used
#             * if not given, automatically determined from input size
#     M2  -   M2>0, number of variables in Y:
#             * if given, only leading M1 columns of X are used
#             * if not given, automatically determined from input size
# 
# OUTPUT PARAMETERS:
#     C   -   array[M1,M2], cross-correlation matrix (zero if N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: c = xalglib.pearsoncorrm2(x, y, n, m1, m2)
SYNTAX: c = xalglib.pearsoncorrm2(x, y)
SYNTAX: c = xalglib.smp_pearsoncorrm2(x, y, n, m1, m2)
SYNTAX: c = xalglib.smp_pearsoncorrm2(x, y)

Examples:   [1]  

rankdata function

#
# This function replaces data in XY by their ranks:
# * XY is processed row-by-row
# * rows are processed separately
# * tied data are correctly handled (tied ranks are calculated)
# * ranking starts from 0, ends at NFeatures-1
# * sum of within-row values is equal to (NFeatures-1)*NFeatures/2
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! ones where expected operations count is less than 100.000
# 
# INPUT PARAMETERS:
#     XY      -   array[NPoints,NFeatures], dataset
#     NPoints -   number of points
#     NFeatures-  number of features
# 
# OUTPUT PARAMETERS:
#     XY      -   data are replaced by their within-row ranks;
#                 ranking starts from 0, ends at NFeatures-1
# 
#   -- ALGLIB --
#      Copyright 18.04.2013 by Bochkanov Sergey
#

SYNTAX: xy = xalglib.rankdata(xy, npoints, nfeatures)
SYNTAX: xy = xalglib.rankdata(xy)
SYNTAX: xy = xalglib.smp_rankdata(xy, npoints, nfeatures)
SYNTAX: xy = xalglib.smp_rankdata(xy)

rankdatacentered function

#
# This function replaces data in XY by their CENTERED ranks:
# * XY is processed row-by-row
# * rows are processed separately
# * tied data are correctly handled (tied ranks are calculated)
# * centered ranks are just usual ranks, but centered in such way  that  sum
#   of within-row values is equal to 0.0.
# * centering is performed by subtracting mean from each row, i.e it changes
#   mean value, but does NOT change higher moments
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! ones where expected operations count is less than 100.000
# 
# INPUT PARAMETERS:
#     XY      -   array[NPoints,NFeatures], dataset
#     NPoints -   number of points
#     NFeatures-  number of features
# 
# OUTPUT PARAMETERS:
#     XY      -   data are replaced by their within-row ranks;
#                 ranking starts from 0, ends at NFeatures-1
# 
#   -- ALGLIB --
#      Copyright 18.04.2013 by Bochkanov Sergey
#

SYNTAX: xy = xalglib.rankdatacentered(xy, npoints, nfeatures)
SYNTAX: xy = xalglib.rankdatacentered(xy)
SYNTAX: xy = xalglib.smp_rankdatacentered(xy, npoints, nfeatures)
SYNTAX: xy = xalglib.smp_rankdatacentered(xy)

sampleadev function

#
# ADev
# 
# Input parameters:
#     X   -   sample
#     N   -   N>=0, sample size:
#             * if given, only leading N elements of X are processed
#             * if not given, automatically determined from size of X
# 
# Output parameters:
#     ADev-   ADev
# 
#   -- ALGLIB --
#      Copyright 06.09.2006 by Bochkanov Sergey
#

SYNTAX: adev = xalglib.sampleadev(x, n)
SYNTAX: adev = xalglib.sampleadev(x)

Examples:   [1]  

samplekurtosis function

#
# Calculation of the kurtosis.
# 
# INPUT PARAMETERS:
#     X       -   sample
#     N       -   N>=0, sample size:
#                 * if given, only leading N elements of X are processed
#                 * if not given, automatically determined from size of X
# 
# NOTE:
# 
# This function return result  which calculated by 'SampleMoments' function
# and stored at 'Kurtosis' variable.
# 
# 
#   -- ALGLIB --
#      Copyright 06.09.2006 by Bochkanov Sergey
#

SYNTAX: result = xalglib.samplekurtosis(x, n)
SYNTAX: result = xalglib.samplekurtosis(x)

samplemean function

#
# Calculation of the mean.
# 
# INPUT PARAMETERS:
#     X       -   sample
#     N       -   N>=0, sample size:
#                 * if given, only leading N elements of X are processed
#                 * if not given, automatically determined from size of X
# 
# NOTE:
# 
# This function return result  which calculated by 'SampleMoments' function
# and stored at 'Mean' variable.
# 
# 
#   -- ALGLIB --
#      Copyright 06.09.2006 by Bochkanov Sergey
#

SYNTAX: result = xalglib.samplemean(x, n)
SYNTAX: result = xalglib.samplemean(x)

samplemedian function

#
# Median calculation.
# 
# Input parameters:
#     X   -   sample (array indexes: [0..N-1])
#     N   -   N>=0, sample size:
#             * if given, only leading N elements of X are processed
#             * if not given, automatically determined from size of X
# 
# Output parameters:
#     Median
# 
#   -- ALGLIB --
#      Copyright 06.09.2006 by Bochkanov Sergey
#

SYNTAX: median = xalglib.samplemedian(x, n)
SYNTAX: median = xalglib.samplemedian(x)

Examples:   [1]  

samplemoments function

#
# Calculation of the distribution moments: mean, variance, skewness, kurtosis.
# 
# INPUT PARAMETERS:
#     X       -   sample
#     N       -   N>=0, sample size:
#                 * if given, only leading N elements of X are processed
#                 * if not given, automatically determined from size of X
# 
# OUTPUT PARAMETERS
#     Mean    -   mean.
#     Variance-   variance.
#     Skewness-   skewness (if variance<>0; zero otherwise).
#     Kurtosis-   kurtosis (if variance<>0; zero otherwise).
# 
# NOTE: variance is calculated by dividing sum of squares by N-1, not N.
# 
#   -- ALGLIB --
#      Copyright 06.09.2006 by Bochkanov Sergey
#

SYNTAX: mean, variance, skewness, kurtosis = xalglib.samplemoments(x, n)
SYNTAX: mean, variance, skewness, kurtosis = xalglib.samplemoments(x)

Examples:   [1]  

samplepercentile function

#
# Percentile calculation.
# 
# Input parameters:
#     X   -   sample (array indexes: [0..N-1])
#     N   -   N>=0, sample size:
#             * if given, only leading N elements of X are processed
#             * if not given, automatically determined from size of X
#     P   -   percentile (0<=P<=1)
# 
# Output parameters:
#     V   -   percentile
# 
#   -- ALGLIB --
#      Copyright 01.03.2008 by Bochkanov Sergey
#

SYNTAX: v = xalglib.samplepercentile(x, n, p)
SYNTAX: v = xalglib.samplepercentile(x, p)

Examples:   [1]  

sampleskewness function

#
# Calculation of the skewness.
# 
# INPUT PARAMETERS:
#     X       -   sample
#     N       -   N>=0, sample size:
#                 * if given, only leading N elements of X are processed
#                 * if not given, automatically determined from size of X
# 
# NOTE:
# 
# This function return result  which calculated by 'SampleMoments' function
# and stored at 'Skewness' variable.
# 
# 
#   -- ALGLIB --
#      Copyright 06.09.2006 by Bochkanov Sergey
#

SYNTAX: result = xalglib.sampleskewness(x, n)
SYNTAX: result = xalglib.sampleskewness(x)

samplevariance function

#
# Calculation of the variance.
# 
# INPUT PARAMETERS:
#     X       -   sample
#     N       -   N>=0, sample size:
#                 * if given, only leading N elements of X are processed
#                 * if not given, automatically determined from size of X
# 
# NOTE:
# 
# This function return result  which calculated by 'SampleMoments' function
# and stored at 'Variance' variable.
# 
# 
#   -- ALGLIB --
#      Copyright 06.09.2006 by Bochkanov Sergey
#

SYNTAX: result = xalglib.samplevariance(x, n)
SYNTAX: result = xalglib.samplevariance(x)

spearmancorr2 function

#
# Spearman's rank correlation coefficient
# 
# Input parameters:
#     X       -   sample 1 (array indexes: [0..N-1])
#     Y       -   sample 2 (array indexes: [0..N-1])
#     N       -   N>=0, sample size:
#                 * if given, only N leading elements of X/Y are processed
#                 * if not given, automatically determined from input sizes
# 
# Result:
#     Spearman's rank correlation coefficient
#     (zero for N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 09.04.2007 by Bochkanov Sergey
#

SYNTAX: result = xalglib.spearmancorr2(x, y, n)
SYNTAX: result = xalglib.spearmancorr2(x, y)

Examples:   [1]  

spearmancorrm function

#
# Spearman's rank correlation matrix
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! with correlation matrices smaller than 128*128.
# 
# INPUT PARAMETERS:
#     X   -   array[N,M], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     N   -   N>=0, number of observations:
#             * if given, only leading N rows of X are used
#             * if not given, automatically determined from input size
#     M   -   M>0, number of variables:
#             * if given, only leading M columns of X are used
#             * if not given, automatically determined from input size
# 
# OUTPUT PARAMETERS:
#     C   -   array[M,M], correlation matrix (zero if N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: c = xalglib.spearmancorrm(x, n, m)
SYNTAX: c = xalglib.spearmancorrm(x)
SYNTAX: c = xalglib.smp_spearmancorrm(x, n, m)
SYNTAX: c = xalglib.smp_spearmancorrm(x)

Examples:   [1]  

spearmancorrm2 function

#
# Spearman's rank cross-correlation matrix
# 
# SMP EDITION OF ALGLIB:
# 
#   ! This function can utilize multicore capabilities of  your system.  In
#   ! order to do this you have to call version with "smp_" prefix,   which
#   ! indicates that multicore code will be used.
#   !
#   ! This note is given for users of SMP edition; if you use GPL  edition,
#   ! or commercial edition of ALGLIB without SMP support, you  still  will
#   ! be able to call smp-version of this function,  but  all  computations
#   ! will be done serially.
#   !
#   ! We recommend you to carefully read ALGLIB Reference  Manual,  section
#   ! called 'SMP support', before using parallel version of this function.
#   !
#   ! You should remember that starting/stopping worker thread always  have
#   ! non-zero cost. Although  multicore  version  is  pretty  efficient on
#   ! large problems, we do not recommend you to use it on small problems -
#   ! with correlation matrices smaller than 128*128.
# 
# INPUT PARAMETERS:
#     X   -   array[N,M1], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     Y   -   array[N,M2], sample matrix:
#             * J-th column corresponds to J-th variable
#             * I-th row corresponds to I-th observation
#     N   -   N>=0, number of observations:
#             * if given, only leading N rows of X/Y are used
#             * if not given, automatically determined from input sizes
#     M1  -   M1>0, number of variables in X:
#             * if given, only leading M1 columns of X are used
#             * if not given, automatically determined from input size
#     M2  -   M2>0, number of variables in Y:
#             * if given, only leading M1 columns of X are used
#             * if not given, automatically determined from input size
# 
# OUTPUT PARAMETERS:
#     C   -   array[M1,M2], cross-correlation matrix (zero if N=0 or N=1)
# 
#   -- ALGLIB --
#      Copyright 28.10.2010 by Bochkanov Sergey
#

SYNTAX: c = xalglib.spearmancorrm2(x, y, n, m1, m2)
SYNTAX: c = xalglib.spearmancorrm2(x, y)
SYNTAX: c = xalglib.smp_spearmancorrm2(x, y, n, m1, m2)
SYNTAX: c = xalglib.smp_spearmancorrm2(x, y)

Examples:   [1]  

spearmanrankcorrelation function

#
# Obsolete function, we recommend to use SpearmanCorr2().
# 
#     -- ALGLIB --
#     Copyright 09.04.2007 by Bochkanov Sergey
#

SYNTAX: result = xalglib.spearmanrankcorrelation(x, y, n)

basestat_d_base example

import xalglib



x = [0,1,4,9,16,25,36,49,64,81]

#
# Here we demonstrate calculation of sample moments
# (mean, variance, skewness, kurtosis)
#
mean, variance, skewness, kurtosis = xalglib.samplemoments(x)
print(mean) # expected 28.5
print(variance) # expected 801.1667
print(skewness) # expected 0.5751
print(kurtosis) # expected -1.2666

#
# Average deviation
#
adev = xalglib.sampleadev(x)
print(adev) # expected 23.2

#
# Median and percentile
#
v = xalglib.samplemedian(x)
print(v) # expected 20.5
p = 0.5
v = xalglib.samplepercentile(x, p)
print(v) # expected 20.5

basestat_d_c2 example

import xalglib



#
# We have two samples - x and y, and want to measure dependency between them
#
x = [0,1,4,9,16,25,36,49,64,81]
y = [0,1,2,3,4,5,6,7,8,9]

#
# Three dependency measures are calculated:
# * covariation
# * Pearson correlation
# * Spearman rank correlation
#
v = xalglib.cov2(x, y)
print(v) # expected 82.5
v = xalglib.pearsoncorr2(x, y)
print(v) # expected 0.9627
v = xalglib.spearmancorr2(x, y)
print(v) # expected 1.000

basestat_d_cm example

import xalglib



#
# X is a sample matrix:
# * I-th row corresponds to I-th observation
# * J-th column corresponds to J-th variable
#
x = [[1,0,1],[1,1,0],[-1,1,0],[-2,-1,1],[-1,0,9]]

#
# Three dependency measures are calculated:
# * covariation
# * Pearson correlation
# * Spearman rank correlation
#
# Result is stored into C, with C[i,j] equal to correlation
# (covariance) between I-th and J-th variables of X.
#
c = xalglib.covm(x)
print(c) # expected [[1.80,0.60,-1.40],[0.60,0.70,-0.80],[-1.40,-0.80,14.70]]
c = xalglib.pearsoncorrm(x)
print(c) # expected [[1.000,0.535,-0.272],[0.535,1.000,-0.249],[-0.272,-0.249,1.000]]
c = xalglib.spearmancorrm(x)
print(c) # expected [[1.000,0.556,-0.306],[0.556,1.000,-0.750],[-0.306,-0.750,1.000]]

basestat_d_cm2 example

import xalglib



#
# X and Y are sample matrices:
# * I-th row corresponds to I-th observation
# * J-th column corresponds to J-th variable
#
x = [[1,0,1],[1,1,0],[-1,1,0],[-2,-1,1],[-1,0,9]]
y = [[2,3],[2,1],[-1,6],[-9,9],[7,1]]

#
# Three dependency measures are calculated:
# * covariation
# * Pearson correlation
# * Spearman rank correlation
#
# Result is stored into C, with C[i,j] equal to correlation
# (covariance) between I-th variable of X and J-th variable of Y.
#
c = xalglib.covm2(x, y)
print(c) # expected [[4.100,-3.250],[2.450,-1.500],[13.450,-5.750]]
c = xalglib.pearsoncorrm2(x, y)
print(c) # expected [[0.519,-0.699],[0.497,-0.518],[0.596,-0.433]]
c = xalglib.spearmancorrm2(x, y)
print(c) # expected [[0.541,-0.649],[0.216,-0.433],[0.433,-0.135]]

bdss module

dsoptimalsplit2 function

#
# Optimal binary classification
# 
# Algorithms finds optimal (=with minimal cross-entropy) binary partition.
# Internal subroutine.
# 
# INPUT PARAMETERS:
#     A       -   array[0..N-1], variable
#     C       -   array[0..N-1], class numbers (0 or 1).
#     N       -   array size
# 
# OUTPUT PARAMETERS:
#     Info    -   completetion code:
#                 * -3, all values of A[] are same (partition is impossible)
#                 * -2, one of C[] is incorrect (<0, >1)
#                 * -1, incorrect pararemets were passed (N<=0).
#                 *  1, OK
#     Threshold-  partiton boundary. Left part contains values which are
#                 strictly less than Threshold. Right part contains values
#                 which are greater than or equal to Threshold.
#     PAL, PBL-   probabilities P(0|v<Threshold) and P(1|v<Threshold)
#     PAR, PBR-   probabilities P(0|v>=Threshold) and P(1|v>=Threshold)
#     CVE     -   cross-validation estimate of cross-entropy
# 
#   -- ALGLIB --
#      Copyright 22.05.2008 by Bochkanov Sergey
#

SYNTAX: info, threshold, pal, pbl, par, pbr, cve = xalglib.dsoptimalsplit2(a, c, n)

dsoptimalsplit2fast function

#
# Optimal partition, internal subroutine. Fast version.
# 
# Accepts:
#     A       array[0..N-1]       array of attributes     array[0..N-1]
#     C       array[0..N-1]       array of class labels
#     TiesBuf array[0..N]         temporaries (ties)
#     CntBuf  array[0..2*NC-1]    temporaries (counts)
#     Alpha                       centering factor (0<=alpha<=1, recommended value - 0.05)
#     BufR    array[0..N-1]       temporaries
#     BufI    array[0..N-1]       temporaries
# 
# Output:
#     Info    error code (">0"=OK, "<0"=bad)
#     RMS     training set RMS error
#     CVRMS   leave-one-out RMS error
# 
# Note:
#     content of all arrays is changed by subroutine;
#     it doesn't allocate temporaries.
# 
#   -- ALGLIB --
#      Copyright 11.12.2008 by Bochkanov Sergey
#

SYNTAX: a, c, tiesbuf, cntbuf, bufr, bufi, info, threshold, rms, cvrms = xalglib.dsoptimalsplit2fast(a, c, tiesbuf, cntbuf, bufr, bufi, n, nc, alpha)

bdsvd module

rmatrixbdsvd function

#
# Singular value decomposition of a bidiagonal matrix (extended algorithm)
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes one  important  improvement   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! Multithreaded acceleration is NOT supported for this function.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# The algorithm performs the singular value decomposition  of  a  bidiagonal
# matrix B (upper or lower) representing it as B = Q*S*P^T, where Q and  P -
# orthogonal matrices, S - diagonal matrix with non-negative elements on the
# main diagonal, in descending order.
# 
# The  algorithm  finds  singular  values.  In  addition,  the algorithm can
# calculate  matrices  Q  and P (more precisely, not the matrices, but their
# product  with  given  matrices U and VT - U*Q and (P^T)*VT)).  Of  course,
# matrices U and VT can be of any type, including identity. Furthermore, the
# algorithm can calculate Q'*C (this product is calculated more  effectively
# than U*Q,  because  this calculation operates with rows instead  of matrix
# columns).
# 
# The feature of the algorithm is its ability to find  all  singular  values
# including those which are arbitrarily close to 0  with  relative  accuracy
# close to  machine precision. If the parameter IsFractionalAccuracyRequired
# is set to True, all singular values will have high relative accuracy close
# to machine precision. If the parameter is set to False, only  the  biggest
# singular value will have relative accuracy  close  to  machine  precision.
# The absolute error of other singular values is equal to the absolute error
# of the biggest singular value.
# 
# Input parameters:
#     D       -   main diagonal of matrix B.
#                 Array whose index ranges within [0..N-1].
#     E       -   superdiagonal (or subdiagonal) of matrix B.
#                 Array whose index ranges within [0..N-2].
#     N       -   size of matrix B.
#     IsUpper -   True, if the matrix is upper bidiagonal.
#     IsFractionalAccuracyRequired -
#                 THIS PARAMETER IS IGNORED SINCE ALGLIB 3.5.0
#                 SINGULAR VALUES ARE ALWAYS SEARCHED WITH HIGH ACCURACY.
#     U       -   matrix to be multiplied by Q.
#                 Array whose indexes range within [0..NRU-1, 0..N-1].
#                 The matrix can be bigger, in that case only the  submatrix
#                 [0..NRU-1, 0..N-1] will be multiplied by Q.
#     NRU     -   number of rows in matrix U.
#     C       -   matrix to be multiplied by Q'.
#                 Array whose indexes range within [0..N-1, 0..NCC-1].
#                 The matrix can be bigger, in that case only the  submatrix
#                 [0..N-1, 0..NCC-1] will be multiplied by Q'.
#     NCC     -   number of columns in matrix C.
#     VT      -   matrix to be multiplied by P^T.
#                 Array whose indexes range within [0..N-1, 0..NCVT-1].
#                 The matrix can be bigger, in that case only the  submatrix
#                 [0..N-1, 0..NCVT-1] will be multiplied by P^T.
#     NCVT    -   number of columns in matrix VT.
# 
# Output parameters:
#     D       -   singular values of matrix B in descending order.
#     U       -   if NRU>0, contains matrix U*Q.
#     VT      -   if NCVT>0, contains matrix (P^T)*VT.
#     C       -   if NCC>0, contains matrix Q'*C.
# 
# Result:
#     True, if the algorithm has converged.
#     False, if the algorithm hasn't converged (rare case).
# 
# NOTE: multiplication U*Q is performed by means of transposition to internal
#       buffer, multiplication and backward transposition. It helps to avoid
#       costly columnwise operations and speed-up algorithm.
# 
# Additional information:
#     The type of convergence is controlled by the internal  parameter  TOL.
#     If the parameter is greater than 0, the singular values will have
#     relative accuracy TOL. If TOL<0, the singular values will have
#     absolute accuracy ABS(TOL)*norm(B).
#     By default, |TOL| falls within the range of 10*Epsilon and 100*Epsilon,
#     where Epsilon is the machine precision. It is not  recommended  to  use
#     TOL less than 10*Epsilon since this will  considerably  slow  down  the
#     algorithm and may not lead to error decreasing.
# 
# History:
#     * 31 March, 2007.
#         changed MAXITR from 6 to 12.
# 
#   -- LAPACK routine (version 3.0) --
#      Univ. of Tennessee, Univ. of California Berkeley, NAG Ltd.,
#      Courant Institute, Argonne National Lab, and Rice University
#      October 31, 1999.
#

SYNTAX: result, d, u, c, vt = xalglib.rmatrixbdsvd(d, e, n, isupper, isfractionalaccuracyrequired, u, nru, c, ncc, vt, ncvt)

bessel module

besseli0 function

#
# Modified Bessel function of order zero
# 
# Returns modified Bessel function of order zero of the
# argument.
# 
# The function is defined as i0(x) = j0( ix ).
# 
# The range is partitioned into the two intervals [0,8] and
# (8, infinity).  Chebyshev polynomial expansions are employed
# in each interval.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0,30        30000       5.8e-16     1.4e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besseli0(x)

besseli1 function

#
# Modified Bessel function of order one
# 
# Returns modified Bessel function of order one of the
# argument.
# 
# The function is defined as i1(x) = -i j1( ix ).
# 
# The range is partitioned into the two intervals [0,8] and
# (8, infinity).  Chebyshev polynomial expansions are employed
# in each interval.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0, 30       30000       1.9e-15     2.1e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1985, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besseli1(x)

besselj0 function

#
# Bessel function of order zero
# 
# Returns Bessel function of order zero of the argument.
# 
# The domain is divided into the intervals [0, 5] and
# (5, infinity). In the first interval the following rational
# approximation is used:
# 
# 
#        2         2
# (w - r  ) (w - r  ) P (w) / Q (w)
#       1         2    3       8
# 
#            2
# where w = x  and the two r's are zeros of the function.
# 
# In the second interval, the Hankel asymptotic expansion
# is employed with two rational functions of degree 6/6
# and 7/7.
# 
# ACCURACY:
# 
#                      Absolute error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0, 30       60000       4.2e-16     1.1e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besselj0(x)

besselj1 function

#
# Bessel function of order one
# 
# Returns Bessel function of order one of the argument.
# 
# The domain is divided into the intervals [0, 8] and
# (8, infinity). In the first interval a 24 term Chebyshev
# expansion is used. In the second, the asymptotic
# trigonometric representation is employed using two
# rational functions of degree 5/5.
# 
# ACCURACY:
# 
#                      Absolute error:
# arithmetic   domain      # trials      peak         rms
#    IEEE      0, 30       30000       2.6e-16     1.1e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besselj1(x)

besseljn function

#
# Bessel function of integer order
# 
# Returns Bessel function of order n, where n is a
# (possibly negative) integer.
# 
# The ratio of jn(x) to j0(x) is computed by backward
# recurrence.  First the ratio jn/jn-1 is found by a
# continued fraction expansion.  Then the recurrence
# relating successive orders is applied until j0 or j1 is
# reached.
# 
# If n = 0 or 1 the routine for j0 or j1 is called
# directly.
# 
# ACCURACY:
# 
#                      Absolute error:
# arithmetic   range      # trials      peak         rms
#    IEEE      0, 30        5000       4.4e-16     7.9e-17
# 
# 
# Not suitable for large n or x. Use jv() (fractional order) instead.
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besseljn(n, x)

besselk0 function

#
# Modified Bessel function, second kind, order zero
# 
# Returns modified Bessel function of the second kind
# of order zero of the argument.
# 
# The range is partitioned into the two intervals [0,8] and
# (8, infinity).  Chebyshev polynomial expansions are employed
# in each interval.
# 
# ACCURACY:
# 
# Tested at 2000 random points between 0 and 8.  Peak absolute
# error (relative when K0 > 1) was 1.46e-14; rms, 4.26e-15.
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0, 30       30000       1.2e-15     1.6e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besselk0(x)

besselk1 function

#
# Modified Bessel function, second kind, order one
# 
# Computes the modified Bessel function of the second kind
# of order one of the argument.
# 
# The range is partitioned into the two intervals [0,2] and
# (2, infinity).  Chebyshev polynomial expansions are employed
# in each interval.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0, 30       30000       1.2e-15     1.6e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besselk1(x)

besselkn function

#
# Modified Bessel function, second kind, integer order
# 
# Returns modified Bessel function of the second kind
# of order n of the argument.
# 
# The range is partitioned into the two intervals [0,9.55] and
# (9.55, infinity).  An ascending power series is used in the
# low range, and an asymptotic expansion in the high range.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0,30        90000       1.8e-8      3.0e-10
# 
# Error is high only near the crossover point x = 9.55
# between the two expansions used.
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1988, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besselkn(nn, x)

bessely0 function

#
# Bessel function of the second kind, order zero
# 
# Returns Bessel function of the second kind, of order
# zero, of the argument.
# 
# The domain is divided into the intervals [0, 5] and
# (5, infinity). In the first interval a rational approximation
# R(x) is employed to compute
#   y0(x)  = R(x)  +   2 * log(x) * j0(x) / PI.
# Thus a call to j0() is required.
# 
# In the second interval, the Hankel asymptotic expansion
# is employed with two rational functions of degree 6/6
# and 7/7.
# 
# 
# 
# ACCURACY:
# 
#  Absolute error, when y0(x) < 1; else relative error:
# 
# arithmetic   domain     # trials      peak         rms
#    IEEE      0, 30       30000       1.3e-15     1.6e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.bessely0(x)

bessely1 function

#
# Bessel function of second kind of order one
# 
# Returns Bessel function of the second kind of order one
# of the argument.
# 
# The domain is divided into the intervals [0, 8] and
# (8, infinity). In the first interval a 25 term Chebyshev
# expansion is used, and a call to j1() is required.
# In the second, the asymptotic trigonometric representation
# is employed using two rational functions of degree 5/5.
# 
# ACCURACY:
# 
#                      Absolute error:
# arithmetic   domain      # trials      peak         rms
#    IEEE      0, 30       30000       1.0e-15     1.3e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.bessely1(x)

besselyn function

#
# Bessel function of second kind of integer order
# 
# Returns Bessel function of order n, where n is a
# (possibly negative) integer.
# 
# The function is evaluated by forward recurrence on
# n, starting with values computed by the routines
# y0() and y1().
# 
# If n = 0 or 1 the routine for y0 or y1 is called
# directly.
# 
# ACCURACY:
#                      Absolute error, except relative
#                      when y > 1:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0, 30       30000       3.4e-15     4.3e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.besselyn(n, x)

betaf module

beta function

#
# Beta function
# 
# 
#                   -     -
#                  | (a) | (b)
# beta( a, b )  =  -----------.
#                     -
#                    | (a+b)
# 
# For large arguments the logarithm of the function is
# evaluated using lgam(), then exponentiated.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE       0,30       30000       8.1e-14     1.1e-14
# 
# Cephes Math Library Release 2.0:  April, 1987
# Copyright 1984, 1987 by Stephen L. Moshier
#

SYNTAX: result = xalglib.beta(a, b)

binomialdistr module

binomialcdistribution function

#
# Complemented binomial distribution
# 
# Returns the sum of the terms k+1 through n of the Binomial
# probability density:
# 
#   n
#   --  ( n )   j      n-j
#   >   (   )  p  (1-p)
#   --  ( j )
#  j=k+1
# 
# The terms are not summed directly; instead the incomplete
# beta integral is employed, according to the formula
# 
# y = bdtrc( k, n, p ) = incbet( k+1, n-k, p ).
# 
# The arguments must be positive, with p ranging from 0 to 1.
# 
# ACCURACY:
# 
# Tested at random points (a,b,p).
# 
#               a,b                     Relative error:
# arithmetic  domain     # trials      peak         rms
#  For p between 0.001 and 1:
#    IEEE     0,100       100000      6.7e-15     8.2e-16
#  For p between 0 and .001:
#    IEEE     0,100       100000      1.5e-13     2.7e-15
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.binomialcdistribution(k, n, p)

binomialdistribution function

#
# Binomial distribution
# 
# Returns the sum of the terms 0 through k of the Binomial
# probability density:
# 
#   k
#   --  ( n )   j      n-j
#   >   (   )  p  (1-p)
#   --  ( j )
#  j=0
# 
# The terms are not summed directly; instead the incomplete
# beta integral is employed, according to the formula
# 
# y = bdtr( k, n, p ) = incbet( n-k, k+1, 1-p ).
# 
# The arguments must be positive, with p ranging from 0 to 1.
# 
# ACCURACY:
# 
# Tested at random points (a,b,p), with p between 0 and 1.
# 
#               a,b                     Relative error:
# arithmetic  domain     # trials      peak         rms
#  For p between 0.001 and 1:
#    IEEE     0,100       100000      4.3e-15     2.6e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.binomialdistribution(k, n, p)

invbinomialdistribution function

#
# Inverse binomial distribution
# 
# Finds the event probability p such that the sum of the
# terms 0 through k of the Binomial probability density
# is equal to the given cumulative probability y.
# 
# This is accomplished using the inverse beta integral
# function and the relation
# 
# 1 - p = incbi( n-k, k+1, y ).
# 
# ACCURACY:
# 
# Tested at random points (a,b,p).
# 
#               a,b                     Relative error:
# arithmetic  domain     # trials      peak         rms
#  For p between 0.001 and 1:
#    IEEE     0,100       100000      2.3e-14     6.4e-16
#    IEEE     0,10000     100000      6.6e-12     1.2e-13
#  For p between 10^-6 and 0.001:
#    IEEE     0,100       100000      2.0e-12     1.3e-14
#    IEEE     0,10000     100000      1.5e-12     3.2e-14
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.invbinomialdistribution(k, n, y)

chebyshev module

chebyshevcalculate function

#
# Calculation of the value of the Chebyshev polynomials of the
# first and second kinds.
# 
# Parameters:
#     r   -   polynomial kind, either 1 or 2.
#     n   -   degree, n>=0
#     x   -   argument, -1 <= x <= 1
# 
# Result:
#     the value of the Chebyshev polynomial at x
#

SYNTAX: result = xalglib.chebyshevcalculate(r, n, x)

chebyshevcoefficients function

#
# Representation of Tn as C[0] + C[1]*X + ... + C[N]*X^N
# 
# Input parameters:
#     N   -   polynomial degree, n>=0
# 
# Output parameters:
#     C   -   coefficients
#

SYNTAX: c = xalglib.chebyshevcoefficients(n)

chebyshevsum function

#
# Summation of Chebyshev polynomials using Clenshaw's recurrence formula.
# 
# This routine calculates
#     c[0]*T0(x) + c[1]*T1(x) + ... + c[N]*TN(x)
# or
#     c[0]*U0(x) + c[1]*U1(x) + ... + c[N]*UN(x)
# depending on the R.
# 
# Parameters:
#     r   -   polynomial kind, either 1 or 2.
#     n   -   degree, n>=0
#     x   -   argument
# 
# Result:
#     the value of the Chebyshev polynomial at x
#

SYNTAX: result = xalglib.chebyshevsum(c, r, n, x)

fromchebyshev function

#
# Conversion of a series of Chebyshev polynomials to a power series.
# 
# Represents A[0]*T0(x) + A[1]*T1(x) + ... + A[N]*Tn(x) as
# B[0] + B[1]*X + ... + B[N]*X^N.
# 
# Input parameters:
#     A   -   Chebyshev series coefficients
#     N   -   degree, N>=0
# 
# Output parameters
#     B   -   power series coefficients
#

SYNTAX: b = xalglib.fromchebyshev(a, n)

chisquaredistr module

chisquarecdistribution function

#
# Complemented Chi-square distribution
# 
# Returns the area under the right hand tail (from x to
# infinity) of the Chi square probability density function
# with v degrees of freedom:
# 
#                                  inf.
#                                    -
#                        1          | |  v/2-1  -t/2
#  P( x | v )   =   -----------     |   t      e     dt
#                    v/2  -       | |
#                   2    | (v/2)   -
#                                   x
# 
# where x is the Chi-square variable.
# 
# The incomplete gamma integral is used, according to the
# formula
# 
# y = chdtr( v, x ) = igamc( v/2.0, x/2.0 ).
# 
# The arguments must both be positive.
# 
# ACCURACY:
# 
# See incomplete gamma function
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.chisquarecdistribution(v, x)

chisquaredistribution function

#
# Chi-square distribution
# 
# Returns the area under the left hand tail (from 0 to x)
# of the Chi square probability density function with
# v degrees of freedom.
# 
# 
#                                   x
#                                    -
#                        1          | |  v/2-1  -t/2
#  P( x | v )   =   -----------     |   t      e     dt
#                    v/2  -       | |
#                   2    | (v/2)   -
#                                   0
# 
# where x is the Chi-square variable.
# 
# The incomplete gamma integral is used, according to the
# formula
# 
# y = chdtr( v, x ) = igam( v/2.0, x/2.0 ).
# 
# The arguments must both be positive.
# 
# ACCURACY:
# 
# See incomplete gamma function
# 
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.chisquaredistribution(v, x)

invchisquaredistribution function

#
# Inverse of complemented Chi-square distribution
# 
# Finds the Chi-square argument x such that the integral
# from x to infinity of the Chi-square density is equal
# to the given cumulative probability y.
# 
# This is accomplished using the inverse gamma integral
# function and the relation
# 
#    x/2 = igami( df/2, y );
# 
# ACCURACY:
# 
# See inverse incomplete gamma function
# 
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.invchisquaredistribution(v, y)

clustering module

ahcreport class

#
# This structure  is used to store results of the agglomerative hierarchical
# clustering (AHC).
# 
# Following information is returned:
# 
# * TerminationType - completion code:
#   * 1   for successful completion of algorithm
#   * -5  inappropriate combination of  clustering  algorithm  and  distance
#         function was used. As for now, it  is  possible  only when  Ward's
#         method is called for dataset with non-Euclidean distance function.
#   In case negative completion code is returned,  other  fields  of  report
#   structure are invalid and should not be used.
# 
# * NPoints contains number of points in the original dataset
# 
# * Z contains information about merges performed  (see below).  Z  contains
#   indexes from the original (unsorted) dataset and it can be used when you
#   need to know what points were merged. However, it is not convenient when
#   you want to build a dendrograd (see below).
# 
# * if  you  want  to  build  dendrogram, you  can use Z, but it is not good
#   option, because Z contains  indexes from  unsorted  dataset.  Dendrogram
#   built from such dataset is likely to have intersections. So, you have to
#   reorder you points before building dendrogram.
#   Permutation which reorders point is returned in P. Another representation
#   of  merges,  which  is  more  convenient for dendorgram construction, is
#   returned in PM.
# 
# * more information on format of Z, P and PM can be found below and in the
#   examples from ALGLIB Reference Manual.
# 
# FORMAL DESCRIPTION OF FIELDS:
#     NPoints         number of points
#     Z               array[NPoints-1,2],  contains   indexes   of  clusters
#                     linked in pairs to  form  clustering  tree.  I-th  row
#                     corresponds to I-th merge:
#                     * Z[I,0] - index of the first cluster to merge
#                     * Z[I,1] - index of the second cluster to merge
#                     * Z[I,0]<Z[I,1]
#                     * clusters are  numbered  from 0 to 2*NPoints-2,  with
#                       indexes from 0 to NPoints-1 corresponding to  points
#                       of the original dataset, and indexes from NPoints to
#                       2*NPoints-2  correspond  to  clusters  generated  by
#                       subsequent  merges  (I-th  row  of Z creates cluster
#                       with index NPoints+I).
# 
#                     IMPORTANT: indexes in Z[] are indexes in the ORIGINAL,
#                     unsorted dataset. In addition to  Z algorithm  outputs
#                     permutation which rearranges points in such  way  that
#                     subsequent merges are  performed  on  adjacent  points
#                     (such order is needed if you want to build dendrogram).
#                     However,  indexes  in  Z  are  related  to   original,
#                     unrearranged sequence of points.
# 
#     P               array[NPoints], permutation which reorders points  for
#                     dendrogram  construction.  P[i] contains  index of the
#                     position  where  we  should  move  I-th  point  of the
#                     original dataset in order to apply merges PZ/PM.
# 
#     PZ              same as Z, but for permutation of points given  by  P.
#                     The  only  thing  which  changed  are  indexes  of the
#                     original points; indexes of clusters remained same.
# 
#     MergeDist       array[NPoints-1], contains distances between  clusters
#                     being merged (MergeDist[i] correspond to merge  stored
#                     in Z[i,...]):
#                     * CLINK, SLINK and  average  linkage algorithms report
#                       "raw", unmodified distance metric.
#                     * Ward's   method   reports   weighted   intra-cluster
#                       variance, which is equal to ||Ca-Cb||^2 * Sa*Sb/(Sa+Sb).
#                       Here  A  and  B  are  clusters being merged, Ca is a
#                       center of A, Cb is a center of B, Sa is a size of A,
#                       Sb is a size of B.
# 
#     PM              array[NPoints-1,6], another representation of  merges,
#                     which is suited for dendrogram construction. It  deals
#                     with rearranged points (permutation P is applied)  and
#                     represents merges in a form which different  from  one
#                     used by Z.
#                     For each I from 0 to NPoints-2, I-th row of PM represents
#                     merge performed on two clusters C0 and C1. Here:
#                     * C0 contains points with indexes PM[I,0]...PM[I,1]
#                     * C1 contains points with indexes PM[I,2]...PM[I,3]
#                     * indexes stored in PM are given for dataset sorted
#                       according to permutation P
#                     * PM[I,1]=PM[I,2]-1 (only adjacent clusters are merged)
#                     * PM[I,0]<=PM[I,1], PM[I,2]<=PM[I,3], i.e. both
#                       clusters contain at least one point
#                     * heights of "subdendrograms" corresponding  to  C0/C1
#                       are stored in PM[I,4]  and  PM[I,5].  Subdendrograms
#                       corresponding   to   single-point   clusters    have
#                       height=0. Dendrogram of the merge result has  height
#                       H=max(H0,H1)+1.
# 
# NOTE: there is one-to-one correspondence between merges described by Z and
#       PM. I-th row of Z describes same merge of clusters as I-th row of PM,
#       with "left" cluster from Z corresponding to the "left" one from PM.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

class ahcreport(object):
    ...

clusterizerstate class

#
# This structure is a clusterization engine.
# 
# You should not try to access its fields directly.
# Use ALGLIB functions in order to work with this object.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

class clusterizerstate(object):
    ...

kmeansreport class

#
# This  structure   is  used  to  store  results of the  k-means  clustering
# algorithm.
# 
# Following information is always returned:
# * NPoints contains number of points in the original dataset
# * TerminationType contains completion code, negative on failure, positive
#   on success
# * K contains number of clusters
# 
# For positive TerminationType we return:
# * NFeatures contains number of variables in the original dataset
# * C, which contains centers found by algorithm
# * CIdx, which maps points of the original dataset to clusters
# 
# FORMAL DESCRIPTION OF FIELDS:
#     NPoints         number of points, >=0
#     NFeatures       number of variables, >=1
#     TerminationType completion code:
#                     * -5 if  distance  type  is  anything  different  from
#                          Euclidean metric
#                     * -3 for degenerate dataset: a) less  than  K  distinct
#                          points, b) K=0 for non-empty dataset.
#                     * +1 for successful completion
#     K               number of clusters
#     C               array[K,NFeatures], rows of the array store centers
#     CIdx            array[NPoints], which contains cluster indexes
#     IterationsCount actual number of iterations performed by clusterizer.
#                     If algorithm performed more than one random restart,
#                     total number of iterations is returned.
#     Energy          merit function, "energy", sum  of  squared  deviations
#                     from cluster centers
# 
#   -- ALGLIB --
#      Copyright 27.11.2012 by Bochkanov Sergey
#

class kmeansreport(object):
    ...

clusterizercreate function

#
# This function initializes clusterizer object. Newly initialized object  is
# empty, i.e. it does not contain dataset. You should use it as follows:
# 1. creation
# 2. dataset is added with ClusterizerSetPoints()
# 3. additional parameters are set
# 3. clusterization is performed with one of the clustering functions
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: s = xalglib.clusterizercreate()

Examples:   [1]  [2]  [3]  [4]  [5]  

clusterizergetdistances function

#
# This function returns distance matrix for dataset
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Agglomerative  hierarchical  clustering  algorithm  has  two   phases:
#   ! distance matrix calculation  and  clustering  itself. Only first phase
#   ! (distance matrix calculation) is accelerated by Intel MKL  and  multi-
#   ! threading. Thus, acceleration is significant only for  medium or high-
#   ! dimensional problems.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     XY      -   array[NPoints,NFeatures], dataset
#     NPoints -   number of points, >=0
#     NFeatures-  number of features, >=1
#     DistType-   distance function:
#                 *  0    Chebyshev distance  (L-inf norm)
#                 *  1    city block distance (L1 norm)
#                 *  2    Euclidean distance  (L2 norm, non-squared)
#                 * 10    Pearson correlation:
#                         dist(a,b) = 1-corr(a,b)
#                 * 11    Absolute Pearson correlation:
#                         dist(a,b) = 1-|corr(a,b)|
#                 * 12    Uncentered Pearson correlation (cosine of the angle):
#                         dist(a,b) = a'*b/(|a|*|b|)
#                 * 13    Absolute uncentered Pearson correlation
#                         dist(a,b) = |a'*b|/(|a|*|b|)
#                 * 20    Spearman rank correlation:
#                         dist(a,b) = 1-rankcorr(a,b)
#                 * 21    Absolute Spearman rank correlation
#                         dist(a,b) = 1-|rankcorr(a,b)|
# 
# OUTPUT PARAMETERS:
#     D       -   array[NPoints,NPoints], distance matrix
#                 (full matrix is returned, with lower and upper triangles)
# 
# NOTE:  different distance functions have different performance penalty:
#        * Euclidean or Pearson correlation distances are the fastest ones
#        * Spearman correlation distance function is a bit slower
#        * city block and Chebyshev distances are order of magnitude slower
# 
#        The reason behing difference in performance is that correlation-based
#        distance functions are computed using optimized linear algebra kernels,
#        while Chebyshev and city block distance functions are computed using
#        simple nested loops with two branches at each iteration.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: d = xalglib.clusterizergetdistances(xy, npoints, nfeatures, disttype)
SYNTAX: d = xalglib.smp_clusterizergetdistances(xy, npoints, nfeatures, disttype)

clusterizergetkclusters function

#
# This function takes as input clusterization report Rep,  desired  clusters
# count K, and builds top K clusters from hierarchical clusterization  tree.
# It returns assignment of points to clusters (array of cluster indexes).
# 
# INPUT PARAMETERS:
#     Rep     -   report from ClusterizerRunAHC() performed on XY
#     K       -   desired number of clusters, 1<=K<=NPoints.
#                 K can be zero only when NPoints=0.
# 
# OUTPUT PARAMETERS:
#     CIdx    -   array[NPoints], I-th element contains cluster index  (from
#                 0 to K-1) for I-th point of the dataset.
#     CZ      -   array[K]. This array allows  to  convert  cluster  indexes
#                 returned by this function to indexes used by  Rep.Z.  J-th
#                 cluster returned by this function corresponds to  CZ[J]-th
#                 cluster stored in Rep.Z/PZ/PM.
#                 It is guaranteed that CZ[I]<CZ[I+1].
# 
# NOTE: K clusters built by this subroutine are assumed to have no hierarchy.
#       Although  they  were  obtained  by  manipulation with top K nodes of
#       dendrogram  (i.e.  hierarchical  decomposition  of  dataset),   this
#       function does not return information about hierarchy.  Each  of  the
#       clusters stand on its own.
# 
# NOTE: Cluster indexes returned by this function  does  not  correspond  to
#       indexes returned in Rep.Z/PZ/PM. Either you work  with  hierarchical
#       representation of the dataset (dendrogram), or you work with  "flat"
#       representation returned by this function.  Each  of  representations
#       has its own clusters indexing system (former uses [0, 2*NPoints-2]),
#       while latter uses [0..K-1]), although  it  is  possible  to  perform
#       conversion from one system to another by means of CZ array, returned
#       by this function, which allows you to convert indexes stored in CIdx
#       to the numeration system used by Rep.Z.
# 
# NOTE: this subroutine is optimized for moderate values of K. Say, for  K=5
#       it will perform many times faster than  for  K=100.  Its  worst-case
#       performance is O(N*K), although in average case  it  perform  better
#       (up to O(N*log(K))).
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: cidx, cz = xalglib.clusterizergetkclusters(rep, k)

Examples:   [1]  [2]  

clusterizerrunahc function

#
# This function performs agglomerative hierarchical clustering
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Agglomerative  hierarchical  clustering  algorithm  has  two   phases:
#   ! distance matrix calculation  and  clustering  itself. Only first phase
#   ! (distance matrix calculation) is accelerated by Intel MKL  and  multi-
#   ! threading. Thus, acceleration is significant only for  medium or high-
#   ! dimensional problems.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     S       -   clusterizer state, initialized by ClusterizerCreate()
# 
# OUTPUT PARAMETERS:
#     Rep     -   clustering results; see description of AHCReport
#                 structure for more information.
# 
# NOTE 1: hierarchical clustering algorithms require large amounts of memory.
#         In particular, this implementation needs  sizeof(double)*NPoints^2
#         bytes, which are used to store distance matrix. In  case  we  work
#         with user-supplied matrix, this amount is multiplied by 2 (we have
#         to store original matrix and to work with its copy).
# 
#         For example, problem with 10000 points  would require 800M of RAM,
#         even when working in a 1-dimensional space.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: rep = xalglib.clusterizerrunahc(s)
SYNTAX: rep = xalglib.smp_clusterizerrunahc(s)

Examples:   [1]  [2]  [3]  [4]  [5]  

clusterizerrunkmeans function

#
# This function performs clustering by k-means++ algorithm.
# 
# You may change algorithm properties by calling:
# * ClusterizerSetKMeansLimits() to change number of restarts or iterations
# * ClusterizerSetKMeansInit() to change initialization algorithm
# 
# By  default,  one  restart  and  unlimited number of iterations are  used.
# Initialization algorithm is chosen automatically.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes  two important  improvements  of
#   ! this function:
#   ! * multicore support (can be used from C# and C++)
#   ! * access to high-performance C++ core (actual for C# users)
#   !
#   ! K-means clustering  algorithm has two  phases:  selection  of  initial
#   ! centers  and  clustering  itself.  ALGLIB  parallelizes  both  phases.
#   ! Parallel version is optimized for the following  scenario:  medium  or
#   ! high-dimensional problem (20 or more dimensions) with large number  of
#   ! points and clusters. However, some speed-up can be obtained even  when
#   ! assumptions above are violated.
#   !
#   ! As for native-vs-managed comparison, working with native  core  brings
#   ! 30-40% improvement in speed over pure C# version of ALGLIB.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     S       -   clusterizer state, initialized by ClusterizerCreate()
#     K       -   number of clusters, K>=0.
#                 K  can  be  zero only when algorithm is called  for  empty
#                 dataset,  in   this   case   completion  code  is  set  to
#                 success (+1).
#                 If  K=0  and  dataset  size  is  non-zero,  we   can   not
#                 meaningfully assign points to some center  (there  are  no
#                 centers because K=0) and  return  -3  as  completion  code
#                 (failure).
# 
# OUTPUT PARAMETERS:
#     Rep     -   clustering results; see description of KMeansReport
#                 structure for more information.
# 
# NOTE 1: k-means  clustering  can  be  performed  only  for  datasets  with
#         Euclidean  distance  function.  Algorithm  will  return   negative
#         completion code in Rep.TerminationType in case dataset  was  added
#         to clusterizer with DistType other than Euclidean (or dataset  was
#         specified by distance matrix instead of explicitly given points).
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: rep = xalglib.clusterizerrunkmeans(s, k)
SYNTAX: rep = xalglib.smp_clusterizerrunkmeans(s, k)

clusterizerseparatedbycorr function

#
# This  function  accepts  AHC  report  Rep,  desired  maximum  intercluster
# correlation and returns top clusters from hierarchical clusterization tree
# which are separated by correlation R or LOWER.
# 
# It returns assignment of points to clusters (array of cluster indexes).
# 
# There is one more function with similar name - ClusterizerSeparatedByDist,
# which returns clusters with intercluster distance equal  to  R  or  HIGHER
# (note: higher for distance, lower for correlation).
# 
# INPUT PARAMETERS:
#     Rep     -   report from ClusterizerRunAHC() performed on XY
#     R       -   desired maximum intercluster correlation, -1<=R<=+1
# 
# OUTPUT PARAMETERS:
#     K       -   number of clusters, 1<=K<=NPoints
#     CIdx    -   array[NPoints], I-th element contains cluster index  (from
#                 0 to K-1) for I-th point of the dataset.
#     CZ      -   array[K]. This array allows  to  convert  cluster  indexes
#                 returned by this function to indexes used by  Rep.Z.  J-th
#                 cluster returned by this function corresponds to  CZ[J]-th
#                 cluster stored in Rep.Z/PZ/PM.
#                 It is guaranteed that CZ[I]<CZ[I+1].
# 
# NOTE: K clusters built by this subroutine are assumed to have no hierarchy.
#       Although  they  were  obtained  by  manipulation with top K nodes of
#       dendrogram  (i.e.  hierarchical  decomposition  of  dataset),   this
#       function does not return information about hierarchy.  Each  of  the
#       clusters stand on its own.
# 
# NOTE: Cluster indexes returned by this function  does  not  correspond  to
#       indexes returned in Rep.Z/PZ/PM. Either you work  with  hierarchical
#       representation of the dataset (dendrogram), or you work with  "flat"
#       representation returned by this function.  Each  of  representations
#       has its own clusters indexing system (former uses [0, 2*NPoints-2]),
#       while latter uses [0..K-1]), although  it  is  possible  to  perform
#       conversion from one system to another by means of CZ array, returned
#       by this function, which allows you to convert indexes stored in CIdx
#       to the numeration system used by Rep.Z.
# 
# NOTE: this subroutine is optimized for moderate values of K. Say, for  K=5
#       it will perform many times faster than  for  K=100.  Its  worst-case
#       performance is O(N*K), although in average case  it  perform  better
#       (up to O(N*log(K))).
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: k, cidx, cz = xalglib.clusterizerseparatedbycorr(rep, r)

clusterizerseparatedbydist function

#
# This  function  accepts  AHC  report  Rep,  desired  minimum  intercluster
# distance and returns top clusters from  hierarchical  clusterization  tree
# which are separated by distance R or HIGHER.
# 
# It returns assignment of points to clusters (array of cluster indexes).
# 
# There is one more function with similar name - ClusterizerSeparatedByCorr,
# which returns clusters with intercluster correlation equal to R  or  LOWER
# (note: higher for distance, lower for correlation).
# 
# INPUT PARAMETERS:
#     Rep     -   report from ClusterizerRunAHC() performed on XY
#     R       -   desired minimum intercluster distance, R>=0
# 
# OUTPUT PARAMETERS:
#     K       -   number of clusters, 1<=K<=NPoints
#     CIdx    -   array[NPoints], I-th element contains cluster index  (from
#                 0 to K-1) for I-th point of the dataset.
#     CZ      -   array[K]. This array allows  to  convert  cluster  indexes
#                 returned by this function to indexes used by  Rep.Z.  J-th
#                 cluster returned by this function corresponds to  CZ[J]-th
#                 cluster stored in Rep.Z/PZ/PM.
#                 It is guaranteed that CZ[I]<CZ[I+1].
# 
# NOTE: K clusters built by this subroutine are assumed to have no hierarchy.
#       Although  they  were  obtained  by  manipulation with top K nodes of
#       dendrogram  (i.e.  hierarchical  decomposition  of  dataset),   this
#       function does not return information about hierarchy.  Each  of  the
#       clusters stand on its own.
# 
# NOTE: Cluster indexes returned by this function  does  not  correspond  to
#       indexes returned in Rep.Z/PZ/PM. Either you work  with  hierarchical
#       representation of the dataset (dendrogram), or you work with  "flat"
#       representation returned by this function.  Each  of  representations
#       has its own clusters indexing system (former uses [0, 2*NPoints-2]),
#       while latter uses [0..K-1]), although  it  is  possible  to  perform
#       conversion from one system to another by means of CZ array, returned
#       by this function, which allows you to convert indexes stored in CIdx
#       to the numeration system used by Rep.Z.
# 
# NOTE: this subroutine is optimized for moderate values of K. Say, for  K=5
#       it will perform many times faster than  for  K=100.  Its  worst-case
#       performance is O(N*K), although in average case  it  perform  better
#       (up to O(N*log(K))).
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: k, cidx, cz = xalglib.clusterizerseparatedbydist(rep, r)

clusterizersetahcalgo function

#
# This function sets agglomerative hierarchical clustering algorithm
# 
# INPUT PARAMETERS:
#     S       -   clusterizer state, initialized by ClusterizerCreate()
#     Algo    -   algorithm type:
#                 * 0     complete linkage (default algorithm)
#                 * 1     single linkage
#                 * 2     unweighted average linkage
#                 * 3     weighted average linkage
#                 * 4     Ward's method
# 
# NOTE: Ward's method works correctly only with Euclidean  distance,  that's
#       why algorithm will return negative termination  code  (failure)  for
#       any other distance type.
# 
#       It is possible, however,  to  use  this  method  with  user-supplied
#       distance matrix. It  is  your  responsibility  to pass one which was
#       calculated with Euclidean distance function.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.clusterizersetahcalgo(s, algo)

Examples:   [1]  [2]  [3]  [4]  [5]  

clusterizersetdistances function

#
# This function adds dataset given by distance  matrix  to  the  clusterizer
# structure. It is important that dataset is not  given  explicitly  -  only
# distance matrix is given.
# 
# This function overrides all previous calls  of  ClusterizerSetPoints()  or
# ClusterizerSetDistances().
# 
# INPUT PARAMETERS:
#     S       -   clusterizer state, initialized by ClusterizerCreate()
#     D       -   array[NPoints,NPoints], distance matrix given by its upper
#                 or lower triangle (main diagonal is  ignored  because  its
#                 entries are expected to be zero).
#     NPoints -   number of points
#     IsUpper -   whether upper or lower triangle of D is given.
# 
# NOTE 1: different clustering algorithms have different limitations:
#         * agglomerative hierarchical clustering algorithms may be used with
#           any kind of distance metric, including one  which  is  given  by
#           distance matrix
#         * k-means++ clustering algorithm may be used only  with  Euclidean
#           distance function and explicitly given points - it  can  not  be
#           used with dataset given by distance matrix
#         Thus, if you call this function, you will be unable to use k-means
#         clustering algorithm to process your problem.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.clusterizersetdistances(s, d, npoints, isupper)
SYNTAX: xalglib.clusterizersetdistances(s, d, isupper)

Examples:   [1]  

clusterizersetkmeansinit function

#
# This function sets k-means  initialization  algorithm.  Several  different
# algorithms can be chosen, including k-means++.
# 
# INPUT PARAMETERS:
#     S       -   clusterizer state, initialized by ClusterizerCreate()
#     InitAlgo-   initialization algorithm:
#                 * 0  automatic selection ( different  versions  of  ALGLIB
#                      may select different algorithms)
#                 * 1  random initialization
#                 * 2  k-means++ initialization  (best  quality  of  initial
#                      centers, but long  non-parallelizable  initialization
#                      phase with bad cache locality)
#                 * 3  "fast-greedy"  algorithm  with  efficient,  easy   to
#                      parallelize initialization. Quality of initial centers
#                      is  somewhat  worse  than  that  of  k-means++.  This
#                      algorithm is a default one in the current version  of
#                      ALGLIB.
#                 *-1  "debug" algorithm which always selects first  K  rows
#                      of dataset; this algorithm is used for debug purposes
#                      only. Do not use it in the industrial code!
# 
#   -- ALGLIB --
#      Copyright 21.01.2015 by Bochkanov Sergey
#

SYNTAX: xalglib.clusterizersetkmeansinit(s, initalgo)

clusterizersetkmeanslimits function

#
# This  function  sets k-means properties:  number  of  restarts and maximum
# number of iterations per one run.
# 
# INPUT PARAMETERS:
#     S       -   clusterizer state, initialized by ClusterizerCreate()
#     Restarts-   restarts count, >=1.
#                 k-means++ algorithm performs several restarts and  chooses
#                 best set of centers (one with minimum squared distance).
#     MaxIts  -   maximum number of k-means iterations performed during  one
#                 run. >=0, zero value means that algorithm performs unlimited
#                 number of iterations.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.clusterizersetkmeanslimits(s, restarts, maxits)

clusterizersetpoints function

#
# This function adds dataset to the clusterizer structure.
# 
# This function overrides all previous calls  of  ClusterizerSetPoints()  or
# ClusterizerSetDistances().
# 
# INPUT PARAMETERS:
#     S       -   clusterizer state, initialized by ClusterizerCreate()
#     XY      -   array[NPoints,NFeatures], dataset
#     NPoints -   number of points, >=0
#     NFeatures-  number of features, >=1
#     DistType-   distance function:
#                 *  0    Chebyshev distance  (L-inf norm)
#                 *  1    city block distance (L1 norm)
#                 *  2    Euclidean distance  (L2 norm), non-squared
#                 * 10    Pearson correlation:
#                         dist(a,b) = 1-corr(a,b)
#                 * 11    Absolute Pearson correlation:
#                         dist(a,b) = 1-|corr(a,b)|
#                 * 12    Uncentered Pearson correlation (cosine of the angle):
#                         dist(a,b) = a'*b/(|a|*|b|)
#                 * 13    Absolute uncentered Pearson correlation
#                         dist(a,b) = |a'*b|/(|a|*|b|)
#                 * 20    Spearman rank correlation:
#                         dist(a,b) = 1-rankcorr(a,b)
#                 * 21    Absolute Spearman rank correlation
#                         dist(a,b) = 1-|rankcorr(a,b)|
# 
# NOTE 1: different distance functions have different performance penalty:
#         * Euclidean or Pearson correlation distances are the fastest ones
#         * Spearman correlation distance function is a bit slower
#         * city block and Chebyshev distances are order of magnitude slower
# 
#         The reason behing difference in performance is that correlation-based
#         distance functions are computed using optimized linear algebra kernels,
#         while Chebyshev and city block distance functions are computed using
#         simple nested loops with two branches at each iteration.
# 
# NOTE 2: different clustering algorithms have different limitations:
#         * agglomerative hierarchical clustering algorithms may be used with
#           any kind of distance metric
#         * k-means++ clustering algorithm may be used only  with  Euclidean
#           distance function
#         Thus, list of specific clustering algorithms you may  use  depends
#         on distance function you specify when you set your dataset.
# 
#   -- ALGLIB --
#      Copyright 10.07.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.clusterizersetpoints(s, xy, npoints, nfeatures, disttype)
SYNTAX: xalglib.clusterizersetpoints(s, xy, disttype)

Examples:   [1]  [2]  [3]  [4]  [5]  

clst_ahc example

import xalglib



#
# The very simple clusterization example
#
# We have a set of points in 2D space:
#     (P0,P1,P2,P3,P4) = ((1,1),(1,2),(4,1),(2,3),(4,1.5))
#
#  |
#  |     P3
#  |
#  | P1          
#  |             P4
#  | P0          P2
#  |-------------------------
#
# We want to perform Agglomerative Hierarchic Clusterization (AHC),
# using complete linkage (default algorithm) and Euclidean distance
# (default metric).
#
# In order to do that, we:
# * create clusterizer with clusterizercreate()
# * set points XY and metric (2=Euclidean) with clusterizersetpoints()
# * run AHC algorithm with clusterizerrunahc
#
# You may see that clusterization itself is a minor part of the example,
# most of which is dominated by comments :)
#
xy = [[1,1],[1,2],[4,1],[2,3],[4,1.5]]

s = xalglib.clusterizercreate()
xalglib.clusterizersetpoints(s, xy, 2)
rep = xalglib.clusterizerrunahc(s)

#
# Now we've built our clusterization tree. Rep.z contains information which
# is required to build dendrogram. I-th row of rep.z represents one merge
# operation, with first cluster to merge having index rep.z[I,0] and second
# one having index rep.z[I,1]. Merge result has index NPoints+I.
#
# Clusters with indexes less than NPoints are single-point initial clusters,
# while ones with indexes from NPoints to 2*NPoints-2 are multi-point
# clusters created during merges.
#
# In our example, Z=[[2,4], [0,1], [3,6], [5,7]]
#
# It means that:
# * first, we merge C2=(P2) and C4=(P4),    and create C5=(P2,P4)
# * then, we merge  C2=(P0) and C1=(P1),    and create C6=(P0,P1)
# * then, we merge  C3=(P3) and C6=(P0,P1), and create C7=(P0,P1,P3)
# * finally, we merge C5 and C7 and create C8=(P0,P1,P2,P3,P4)
#
# Thus, we have following dendrogram:
#  
#      ------8-----
#      |          |
#      |      ----7----
#      |      |       |
#   ---5---   |    ---6---
#   |     |   |    |     |
#   P2   P4   P3   P0   P1
#
print(rep.z) # expected [[2,4],[0,1],[3,6],[5,7]]

#
# We've built dendrogram above by reordering our dataset.
#
# Without such reordering it would be impossible to build dendrogram without
# intersections. Luckily, ahcreport structure contains two additional fields
# which help to build dendrogram from your data:
# * rep.p, which contains permutation applied to dataset
# * rep.pm, which contains another representation of merges 
#
# In our example we have:
# * P=[3,4,0,2,1]
# * PZ=[[0,0,1,1,0,0],[3,3,4,4,0,0],[2,2,3,4,0,1],[0,1,2,4,1,2]]
#
# Permutation array P tells us that P0 should be moved to position 3,
# P1 moved to position 4, P2 moved to position 0 and so on:
#
#   (P0 P1 P2 P3 P4) => (P2 P4 P3 P0 P1)
#
# Merges array PZ tells us how to perform merges on the sorted dataset.
# One row of PZ corresponds to one merge operations, with first pair of
# elements denoting first of the clusters to merge (start index, end
# index) and next pair of elements denoting second of the clusters to
# merge. Clusters being merged are always adjacent, with first one on
# the left and second one on the right.
#
# For example, first row of PZ tells us that clusters [0,0] and [1,1] are
# merged (single-point clusters, with first one containing P2 and second
# one containing P4). Third row of PZ tells us that we merge one single-
# point cluster [2,2] with one two-point cluster [3,4].
#
# There are two more elements in each row of PZ. These are the helper
# elements, which denote HEIGHT (not size) of left and right subdendrograms.
# For example, according to PZ, first two merges are performed on clusterization
# trees of height 0, while next two merges are performed on 0-1 and 1-2
# pairs of trees correspondingly.
#
print(rep.p) # expected [3,4,0,2,1]
print(rep.pm) # expected [[0,0,1,1,0,0],[3,3,4,4,0,0],[2,2,3,4,0,1],[0,1,2,4,1,2]]

clst_distance example

import xalglib



#
# We have three points in 4D space:
#     (P0,P1,P2) = ((1, 2, 1, 2), (6, 7, 6, 7), (7, 6, 7, 6))
#
# We want to try clustering them with different distance functions.
# Distance function is chosen when we add dataset to the clusterizer.
# We can choose several distance types - Euclidean, city block, Chebyshev,
# several correlation measures or user-supplied distance matrix.
#
# Here we'll try three distances: Euclidean, Pearson correlation,
# user-supplied distance matrix. Different distance functions lead
# to different choices being made by algorithm during clustering.
#
xy = [[1, 2, 1, 2], [6, 7, 6, 7], [7, 6, 7, 6]]
s = xalglib.clusterizercreate()

# With Euclidean distance function (disttype=2) two closest points
# are P1 and P2, thus:
# * first, we merge P1 and P2 to form C3=[P1,P2]
# * second, we merge P0 and C3 to form C4=[P0,P1,P2]
disttype = 2
xalglib.clusterizersetpoints(s, xy, disttype)
rep = xalglib.clusterizerrunahc(s)
print(rep.z) # expected [[1,2],[0,3]]

# With Pearson correlation distance function (disttype=10) situation
# is different - distance between P0 and P1 is zero, thus:
# * first, we merge P0 and P1 to form C3=[P0,P1]
# * second, we merge P2 and C3 to form C4=[P0,P1,P2]
disttype = 10
xalglib.clusterizersetpoints(s, xy, disttype)
rep = xalglib.clusterizerrunahc(s)
print(rep.z) # expected [[0,1],[2,3]]

# Finally, we try clustering with user-supplied distance matrix:
#     [ 0 3 1 ]
# P = [ 3 0 3 ], where P[i,j] = dist(Pi,Pj)
#     [ 1 3 0 ]
#
# * first, we merge P0 and P2 to form C3=[P0,P2]
# * second, we merge P1 and C3 to form C4=[P0,P1,P2]
d = [[0,3,1],[3,0,3],[1,3,0]]
xalglib.clusterizersetdistances(s, d, True)
rep = xalglib.clusterizerrunahc(s)
print(rep.z) # expected [[0,2],[1,3]]

clst_kclusters example

import xalglib



#
# We have a set of points in 2D space:
#     (P0,P1,P2,P3,P4) = ((1,1),(1,2),(4,1),(2,3),(4,1.5))
#
#  |
#  |     P3
#  |
#  | P1          
#  |             P4
#  | P0          P2
#  |-------------------------
#
# We perform Agglomerative Hierarchic Clusterization (AHC) and we want
# to get top K clusters from clusterization tree for different K.
#
xy = [[1,1],[1,2],[4,1],[2,3],[4,1.5]]

s = xalglib.clusterizercreate()
xalglib.clusterizersetpoints(s, xy, 2)
rep = xalglib.clusterizerrunahc(s)

# with K=5, every points is assigned to its own cluster:
# C0=P0, C1=P1 and so on...
cidx, cz = xalglib.clusterizergetkclusters(rep, 5)
print(cidx) # expected [0,1,2,3,4]

# with K=1 we have one large cluster C0=[P0,P1,P2,P3,P4,P5]
cidx, cz = xalglib.clusterizergetkclusters(rep, 1)
print(cidx) # expected [0,0,0,0,0]

# with K=3 we have three clusters C0=[P3], C1=[P2,P4], C2=[P0,P1]
cidx, cz = xalglib.clusterizergetkclusters(rep, 3)
print(cidx) # expected [2,2,1,0,1]

clst_kmeans example

import xalglib



#
# The very simple clusterization example
#
# We have a set of points in 2D space:
#     (P0,P1,P2,P3,P4) = ((1,1),(1,2),(4,1),(2,3),(4,1.5))
#
#  |
#  |     P3
#  |
#  | P1          
#  |             P4
#  | P0          P2
#  |-------------------------
#
# We want to perform k-means++ clustering with K=2.
#
# In order to do that, we:
# * create clusterizer with clusterizercreate()
# * set points XY and metric (must be Euclidean, distype=2) with clusterizersetpoints()
# * (optional) set number of restarts from random positions to 5
# * run k-means algorithm with clusterizerrunkmeans()
#
# You may see that clusterization itself is a minor part of the example,
# most of which is dominated by comments :)
#
xy = [[1,1],[1,2],[4,1],[2,3],[4,1.5]]

s = xalglib.clusterizercreate()
xalglib.clusterizersetpoints(s, xy, 2)
xalglib.clusterizersetkmeanslimits(s, 5, 0)
rep = xalglib.clusterizerrunkmeans(s, 2)

#
# We've performed clusterization, and it succeeded (completion code is +1).
#
# Now first center is stored in the first row of rep.c, second one is stored
# in the second row. rep.cidx can be used to determine which center is
# closest to some specific point of the dataset.
#
print(rep.terminationtype) # expected 1

# We called clusterizersetpoints() with disttype=2 because k-means++
# algorithm does NOT support metrics other than Euclidean. But what if we
# try to use some other metric?
#
# We change metric type by calling clusterizersetpoints() one more time,
# and try to run k-means algo again. It fails.
#
xalglib.clusterizersetpoints(s, xy, 0)
rep = xalglib.clusterizerrunkmeans(s, 2)
print(rep.terminationtype) # expected -5

clst_linkage example

import xalglib



#
# We have a set of points in 1D space:
#     (P0,P1,P2,P3,P4) = (1, 3, 10, 16, 20)
#
# We want to perform Agglomerative Hierarchic Clusterization (AHC),
# using either complete or single linkage and Euclidean distance
# (default metric).
#
# First two steps merge P0/P1 and P3/P4 independently of the linkage type.
# However, third step depends on linkage type being used:
# * in case of complete linkage P2=10 is merged with [P0,P1]
# * in case of single linkage P2=10 is merged with [P3,P4]
#
xy = [[1],[3],[10],[16],[20]]

s = xalglib.clusterizercreate()
xalglib.clusterizersetpoints(s, xy, 2)

# use complete linkage, reduce set down to 2 clusters.
# print clusterization with clusterizergetkclusters(2).
# P2 must belong to [P0,P1]
xalglib.clusterizersetahcalgo(s, 0)
rep = xalglib.clusterizerrunahc(s)
cidx, cz = xalglib.clusterizergetkclusters(rep, 2)
print(cidx) # expected [1,1,1,0,0]

# use single linkage, reduce set down to 2 clusters.
# print clusterization with clusterizergetkclusters(2).
# P2 must belong to [P2,P3]
xalglib.clusterizersetahcalgo(s, 1)
rep = xalglib.clusterizerrunahc(s)
cidx, cz = xalglib.clusterizergetkclusters(rep, 2)
print(cidx) # expected [0,0,1,1,1]

conv module

convc1d function

#
# 1-dimensional complex convolution.
# 
# For given A/B returns conv(A,B) (non-circular). Subroutine can automatically
# choose between three implementations: straightforward O(M*N)  formula  for
# very small N (or M), overlap-add algorithm for  cases  where  max(M,N)  is
# significantly larger than min(M,N), but O(M*N) algorithm is too slow,  and
# general FFT-based formula for cases where two previois algorithms are  too
# slow.
# 
# Algorithm has max(M,N)*log(max(M,N)) complexity for any M/N.
# 
# INPUT PARAMETERS
#     A   -   array[0..M-1] - complex function to be transformed
#     M   -   problem size
#     B   -   array[0..N-1] - complex function to be transformed
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     R   -   convolution: A*B. array[0..N+M-2].
# 
# NOTE:
#     It is assumed that A is zero at T<0, B is zero too.  If  one  or  both
# functions have non-zero values at negative T's, you  can  still  use  this
# subroutine - just shift its result correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.convc1d(a, m, b, n)

convc1dcircular function

#
# 1-dimensional circular complex convolution.
# 
# For given S/R returns conv(S,R) (circular). Algorithm has linearithmic
# complexity for any M/N.
# 
# IMPORTANT:  normal convolution is commutative,  i.e.   it  is symmetric  -
# conv(A,B)=conv(B,A).  Cyclic convolution IS NOT.  One function - S - is  a
# signal,  periodic function, and another - R - is a response,  non-periodic
# function with limited length.
# 
# INPUT PARAMETERS
#     S   -   array[0..M-1] - complex periodic signal
#     M   -   problem size
#     B   -   array[0..N-1] - complex non-periodic response
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     R   -   convolution: A*B. array[0..M-1].
# 
# NOTE:
#     It is assumed that B is zero at T<0. If  it  has  non-zero  values  at
# negative T's, you can still use this subroutine - just  shift  its  result
# correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: c = xalglib.convc1dcircular(s, m, r, n)

convc1dcircularinv function

#
# 1-dimensional circular complex deconvolution (inverse of ConvC1DCircular()).
# 
# Algorithm has M*log(M)) complexity for any M (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..M-1] - convolved periodic signal, A = conv(R, B)
#     M   -   convolved signal length
#     B   -   array[0..N-1] - non-periodic response
#     N   -   response length
# 
# OUTPUT PARAMETERS
#     R   -   deconvolved signal. array[0..M-1].
# 
# NOTE:
#     deconvolution is unstable process and may result in division  by  zero
# (if your response function is degenerate, i.e. has zero Fourier coefficient).
# 
# NOTE:
#     It is assumed that B is zero at T<0. If  it  has  non-zero  values  at
# negative T's, you can still use this subroutine - just  shift  its  result
# correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.convc1dcircularinv(a, m, b, n)

convc1dinv function

#
# 1-dimensional complex non-circular deconvolution (inverse of ConvC1D()).
# 
# Algorithm has M*log(M)) complexity for any M (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..M-1] - convolved signal, A = conv(R, B)
#     M   -   convolved signal length
#     B   -   array[0..N-1] - response
#     N   -   response length, N<=M
# 
# OUTPUT PARAMETERS
#     R   -   deconvolved signal. array[0..M-N].
# 
# NOTE:
#     deconvolution is unstable process and may result in division  by  zero
# (if your response function is degenerate, i.e. has zero Fourier coefficient).
# 
# NOTE:
#     It is assumed that A is zero at T<0, B is zero too.  If  one  or  both
# functions have non-zero values at negative T's, you  can  still  use  this
# subroutine - just shift its result correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.convc1dinv(a, m, b, n)

convr1d function

#
# 1-dimensional real convolution.
# 
# Analogous to ConvC1D(), see ConvC1D() comments for more details.
# 
# INPUT PARAMETERS
#     A   -   array[0..M-1] - real function to be transformed
#     M   -   problem size
#     B   -   array[0..N-1] - real function to be transformed
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     R   -   convolution: A*B. array[0..N+M-2].
# 
# NOTE:
#     It is assumed that A is zero at T<0, B is zero too.  If  one  or  both
# functions have non-zero values at negative T's, you  can  still  use  this
# subroutine - just shift its result correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.convr1d(a, m, b, n)

convr1dcircular function

#
# 1-dimensional circular real convolution.
# 
# Analogous to ConvC1DCircular(), see ConvC1DCircular() comments for more details.
# 
# INPUT PARAMETERS
#     S   -   array[0..M-1] - real signal
#     M   -   problem size
#     B   -   array[0..N-1] - real response
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     R   -   convolution: A*B. array[0..M-1].
# 
# NOTE:
#     It is assumed that B is zero at T<0. If  it  has  non-zero  values  at
# negative T's, you can still use this subroutine - just  shift  its  result
# correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: c = xalglib.convr1dcircular(s, m, r, n)

convr1dcircularinv function

#
# 1-dimensional complex deconvolution (inverse of ConvC1D()).
# 
# Algorithm has M*log(M)) complexity for any M (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..M-1] - convolved signal, A = conv(R, B)
#     M   -   convolved signal length
#     B   -   array[0..N-1] - response
#     N   -   response length
# 
# OUTPUT PARAMETERS
#     R   -   deconvolved signal. array[0..M-N].
# 
# NOTE:
#     deconvolution is unstable process and may result in division  by  zero
# (if your response function is degenerate, i.e. has zero Fourier coefficient).
# 
# NOTE:
#     It is assumed that B is zero at T<0. If  it  has  non-zero  values  at
# negative T's, you can still use this subroutine - just  shift  its  result
# correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.convr1dcircularinv(a, m, b, n)

convr1dinv function

#
# 1-dimensional real deconvolution (inverse of ConvC1D()).
# 
# Algorithm has M*log(M)) complexity for any M (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..M-1] - convolved signal, A = conv(R, B)
#     M   -   convolved signal length
#     B   -   array[0..N-1] - response
#     N   -   response length, N<=M
# 
# OUTPUT PARAMETERS
#     R   -   deconvolved signal. array[0..M-N].
# 
# NOTE:
#     deconvolution is unstable process and may result in division  by  zero
# (if your response function is degenerate, i.e. has zero Fourier coefficient).
# 
# NOTE:
#     It is assumed that A is zero at T<0, B is zero too.  If  one  or  both
# functions have non-zero values at negative T's, you  can  still  use  this
# subroutine - just shift its result correspondingly.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.convr1dinv(a, m, b, n)

corr module

corrc1d function

#
# 1-dimensional complex cross-correlation.
# 
# For given Pattern/Signal returns corr(Pattern,Signal) (non-circular).
# 
# Correlation is calculated using reduction to  convolution.  Algorithm with
# max(N,N)*log(max(N,N)) complexity is used (see  ConvC1D()  for  more  info
# about performance).
# 
# IMPORTANT:
#     for  historical reasons subroutine accepts its parameters in  reversed
#     order: CorrC1D(Signal, Pattern) = Pattern x Signal (using  traditional
#     definition of cross-correlation, denoting cross-correlation as "x").
# 
# INPUT PARAMETERS
#     Signal  -   array[0..N-1] - complex function to be transformed,
#                 signal containing pattern
#     N       -   problem size
#     Pattern -   array[0..M-1] - complex function to be transformed,
#                 pattern to search withing signal
#     M       -   problem size
# 
# OUTPUT PARAMETERS
#     R       -   cross-correlation, array[0..N+M-2]:
#                 * positive lags are stored in R[0..N-1],
#                   R[i] = sum(conj(pattern[j])*signal[i+j]
#                 * negative lags are stored in R[N..N+M-2],
#                   R[N+M-1-i] = sum(conj(pattern[j])*signal[-i+j]
# 
# NOTE:
#     It is assumed that pattern domain is [0..M-1].  If Pattern is non-zero
# on [-K..M-1],  you can still use this subroutine, just shift result by K.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.corrc1d(signal, n, pattern, m)

corrc1dcircular function

#
# 1-dimensional circular complex cross-correlation.
# 
# For given Pattern/Signal returns corr(Pattern,Signal) (circular).
# Algorithm has linearithmic complexity for any M/N.
# 
# IMPORTANT:
#     for  historical reasons subroutine accepts its parameters in  reversed
#     order:   CorrC1DCircular(Signal, Pattern) = Pattern x Signal    (using
#     traditional definition of cross-correlation, denoting cross-correlation
#     as "x").
# 
# INPUT PARAMETERS
#     Signal  -   array[0..N-1] - complex function to be transformed,
#                 periodic signal containing pattern
#     N       -   problem size
#     Pattern -   array[0..M-1] - complex function to be transformed,
#                 non-periodic pattern to search withing signal
#     M       -   problem size
# 
# OUTPUT PARAMETERS
#     R   -   convolution: A*B. array[0..M-1].
# 
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: c = xalglib.corrc1dcircular(signal, m, pattern, n)

corrr1d function

#
# 1-dimensional real cross-correlation.
# 
# For given Pattern/Signal returns corr(Pattern,Signal) (non-circular).
# 
# Correlation is calculated using reduction to  convolution.  Algorithm with
# max(N,N)*log(max(N,N)) complexity is used (see  ConvC1D()  for  more  info
# about performance).
# 
# IMPORTANT:
#     for  historical reasons subroutine accepts its parameters in  reversed
#     order: CorrR1D(Signal, Pattern) = Pattern x Signal (using  traditional
#     definition of cross-correlation, denoting cross-correlation as "x").
# 
# INPUT PARAMETERS
#     Signal  -   array[0..N-1] - real function to be transformed,
#                 signal containing pattern
#     N       -   problem size
#     Pattern -   array[0..M-1] - real function to be transformed,
#                 pattern to search withing signal
#     M       -   problem size
# 
# OUTPUT PARAMETERS
#     R       -   cross-correlation, array[0..N+M-2]:
#                 * positive lags are stored in R[0..N-1],
#                   R[i] = sum(pattern[j]*signal[i+j]
#                 * negative lags are stored in R[N..N+M-2],
#                   R[N+M-1-i] = sum(pattern[j]*signal[-i+j]
# 
# NOTE:
#     It is assumed that pattern domain is [0..M-1].  If Pattern is non-zero
# on [-K..M-1],  you can still use this subroutine, just shift result by K.
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: r = xalglib.corrr1d(signal, n, pattern, m)

corrr1dcircular function

#
# 1-dimensional circular real cross-correlation.
# 
# For given Pattern/Signal returns corr(Pattern,Signal) (circular).
# Algorithm has linearithmic complexity for any M/N.
# 
# IMPORTANT:
#     for  historical reasons subroutine accepts its parameters in  reversed
#     order:   CorrR1DCircular(Signal, Pattern) = Pattern x Signal    (using
#     traditional definition of cross-correlation, denoting cross-correlation
#     as "x").
# 
# INPUT PARAMETERS
#     Signal  -   array[0..N-1] - real function to be transformed,
#                 periodic signal containing pattern
#     N       -   problem size
#     Pattern -   array[0..M-1] - real function to be transformed,
#                 non-periodic pattern to search withing signal
#     M       -   problem size
# 
# OUTPUT PARAMETERS
#     R   -   convolution: A*B. array[0..M-1].
# 
# 
#   -- ALGLIB --
#      Copyright 21.07.2009 by Bochkanov Sergey
#

SYNTAX: c = xalglib.corrr1dcircular(signal, m, pattern, n)

correlationtests module

pearsoncorrelationsignificance function

#
# Pearson's correlation coefficient significance test
# 
# This test checks hypotheses about whether X  and  Y  are  samples  of  two
# continuous  distributions  having  zero  correlation  or   whether   their
# correlation is non-zero.
# 
# The following tests are performed:
#     * two-tailed test (null hypothesis - X and Y have zero correlation)
#     * left-tailed test (null hypothesis - the correlation  coefficient  is
#       greater than or equal to 0)
#     * right-tailed test (null hypothesis - the correlation coefficient  is
#       less than or equal to 0).
# 
# Requirements:
#     * the number of elements in each sample is not less than 5
#     * normality of distributions of X and Y.
# 
# Input parameters:
#     R   -   Pearson's correlation coefficient for X and Y
#     N   -   number of elements in samples, N>=5.
# 
# Output parameters:
#     BothTails   -   p-value for two-tailed test.
#                     If BothTails is less than the given significance level
#                     the null hypothesis is rejected.
#     LeftTail    -   p-value for left-tailed test.
#                     If LeftTail is less than the given significance level,
#                     the null hypothesis is rejected.
#     RightTail   -   p-value for right-tailed test.
#                     If RightTail is less than the given significance level
#                     the null hypothesis is rejected.
# 
#   -- ALGLIB --
#      Copyright 09.04.2007 by Bochkanov Sergey
#

SYNTAX: bothtails, lefttail, righttail = xalglib.pearsoncorrelationsignificance(r, n)

spearmanrankcorrelationsignificance function

#
# Spearman's rank correlation coefficient significance test
# 
# This test checks hypotheses about whether X  and  Y  are  samples  of  two
# continuous  distributions  having  zero  correlation  or   whether   their
# correlation is non-zero.
# 
# The following tests are performed:
#     * two-tailed test (null hypothesis - X and Y have zero correlation)
#     * left-tailed test (null hypothesis - the correlation  coefficient  is
#       greater than or equal to 0)
#     * right-tailed test (null hypothesis - the correlation coefficient  is
#       less than or equal to 0).
# 
# Requirements:
#     * the number of elements in each sample is not less than 5.
# 
# The test is non-parametric and doesn't require distributions X and Y to be
# normal.
# 
# Input parameters:
#     R   -   Spearman's rank correlation coefficient for X and Y
#     N   -   number of elements in samples, N>=5.
# 
# Output parameters:
#     BothTails   -   p-value for two-tailed test.
#                     If BothTails is less than the given significance level
#                     the null hypothesis is rejected.
#     LeftTail    -   p-value for left-tailed test.
#                     If LeftTail is less than the given significance level,
#                     the null hypothesis is rejected.
#     RightTail   -   p-value for right-tailed test.
#                     If RightTail is less than the given significance level
#                     the null hypothesis is rejected.
# 
#   -- ALGLIB --
#      Copyright 09.04.2007 by Bochkanov Sergey
#

SYNTAX: bothtails, lefttail, righttail = xalglib.spearmanrankcorrelationsignificance(r, n)

datacomp module

kmeansgenerate function

#
# k-means++ clusterization.
# Backward compatibility function, we recommend to use CLUSTERING subpackage
# as better replacement.
# 
#   -- ALGLIB --
#      Copyright 21.03.2009 by Bochkanov Sergey
#

SYNTAX: info, c, xyc = xalglib.kmeansgenerate(xy, npoints, nvars, k, restarts)

dawson module

dawsonintegral function

#
# Dawson's Integral
# 
# Approximates the integral
# 
#                             x
#                             -
#                      2     | |        2
#  dawsn(x)  =  exp( -x  )   |    exp( t  ) dt
#                          | |
#                           -
#                           0
# 
# Three different rational approximations are employed, for
# the intervals 0 to 3.25; 3.25 to 6.25; and 6.25 up.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0,10        10000       6.9e-16     1.0e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.dawsonintegral(x)

densesolver module

densesolverlsreport class

#
# 
#

class densesolverlsreport(object):
    ...

densesolverreport class

#
# 
#

class densesolverreport(object):
    ...

cmatrixlusolve function

#
# Complex dense linear solver for A*x=b with complex N*N A  given  by its LU
# decomposition and N*1 vectors x and b. This is  "slow-but-robust"  version
# of  the  complex  linear  solver  with  additional  features   which   add
# significant performance overhead. Faster version  is  CMatrixLUSolveFast()
# function.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(N^2) complexity
# * condition number estimation
# 
# No iterative refinement is provided because exact form of original matrix
# is not known to subroutine. Use CMatrixSolve or CMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which results in 10-15x  performance  penalty  when  compared
#            ! with "fast" version which just calls triangular solver.
#            !
#            ! This performance penalty is insignificant  when compared with
#            ! cost of large LU decomposition.  However,  if you  call  this
#            ! function many times for the same  left  side,  this  overhead
#            ! BECOMES significant. It  also  becomes significant for small-
#            ! scale problems.
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! CMatrixLUSolveFast() function.
# 
# INPUT PARAMETERS
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, CMatrixLU result
#     P       -   array[0..N-1], pivots array, CMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.cmatrixlusolve(lua, p, n, b)

cmatrixlusolvefast function

#
# Complex dense linear solver for A*x=b with N*N complex A given by  its  LU
# decomposition and N*1 vectors x and b. This is  fast  lightweight  version
# of solver, which is significantly faster than CMatrixLUSolve(),  but  does
# not provide additional information (like condition numbers).
# 
# Algorithm features:
# * O(N^2) complexity
# * no additional time-consuming features, just triangular solver
# 
# INPUT PARAMETERS
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, CMatrixLU result
#     P       -   array[0..N-1], pivots array, CMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
# NOTE: unlike  CMatrixLUSolve(),  this   function   does   NOT   check  for
#       near-degeneracy of input matrix. It  checks  for  EXACT  degeneracy,
#       because this check is easy to do. However,  very  badly  conditioned
#       matrices may went unnoticed.
# 
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.cmatrixlusolvefast(lua, p, n, b)

cmatrixlusolvem function

#
# Dense solver for A*X=B with N*N complex A given by its  LU  decomposition,
# and N*M matrices X and B (multiple right sides).   "Slow-but-feature-rich"
# version of the solver.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(M*N^2) complexity
# * condition number estimation
# 
# No iterative refinement  is provided because exact form of original matrix
# is not known to subroutine. Use CMatrixSolve or CMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant  performance   penalty   when
#            ! compared with "fast"  version  which  just  calls  triangular
#            ! solver.
#            !
#            ! This performance penalty is especially apparent when you  use
#            ! ALGLIB parallel capabilities (condition number estimation  is
#            ! inherently  sequential).  It   also   becomes significant for
#            ! small-scale problems.
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! CMatrixLUSolveMFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. Triangular solver is relatively easy to parallelize.
#   ! However, parallelization will be efficient  only for  large number  of
#   ! right parts M.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, RMatrixLU result
#     P       -   array[0..N-1], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N,M], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.cmatrixlusolvem(lua, p, n, b, m)
SYNTAX: info, rep, x = xalglib.smp_cmatrixlusolvem(lua, p, n, b, m)

cmatrixlusolvemfast function

#
# Dense solver for A*X=B with N*N complex A given by its  LU  decomposition,
# and N*M matrices X and B (multiple  right  sides).  "Fast-but-lightweight"
# version of the solver.
# 
# Algorithm features:
# * O(M*N^2) complexity
# * no additional time-consuming features
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. Triangular solver is relatively easy to parallelize.
#   ! However, parallelization will be efficient  only for  large number  of
#   ! right parts M.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, RMatrixLU result
#     P       -   array[0..N-1], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N,M]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.cmatrixlusolvemfast(lua, p, n, b, m)
SYNTAX: b, info = xalglib.smp_cmatrixlusolvemfast(lua, p, n, b, m)

cmatrixmixedsolve function

#
# Dense solver. Same as RMatrixMixedSolve(), but for complex matrices.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * iterative refinement
# * O(N^2) complexity
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, CMatrixLU result
#     P       -   array[0..N-1], pivots array, CMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.cmatrixmixedsolve(a, lua, p, n, b)

cmatrixmixedsolvem function

#
# Dense solver. Same as RMatrixMixedSolveM(), but for complex matrices.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * iterative refinement
# * O(M*N^2) complexity
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, CMatrixLU result
#     P       -   array[0..N-1], pivots array, CMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N,M], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.cmatrixmixedsolvem(a, lua, p, n, b, m)

cmatrixsolve function

#
# Complex dense solver for A*x=B with N*N complex matrix A and  N*1  complex
# vectors x and b. "Slow-but-feature-rich" version of the solver.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * iterative refinement
# * O(N^3) complexity
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear  system
#            ! and  performs  iterative   refinement,   which   results   in
#            ! significant performance penalty  when  compared  with  "fast"
#            ! version  which  just  performs  LU  decomposition  and  calls
#            ! triangular solver.
#            !
#            ! This  performance  penalty  is  especially  visible  in   the
#            ! multithreaded mode, because both condition number  estimation
#            ! and   iterative    refinement   are   inherently   sequential
#            ! calculations.
#            !
#            ! Thus, if you need high performance and if you are pretty sure
#            ! that your system is well conditioned, we  strongly  recommend
#            ! you to use faster solver, CMatrixSolveFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.cmatrixsolve(a, n, b)
SYNTAX: info, rep, x = xalglib.smp_cmatrixsolve(a, n, b)

cmatrixsolvefast function

#
# Complex dense solver for A*x=B with N*N complex matrix A and  N*1  complex
# vectors x and b. "Fast-but-lightweight" version of the solver.
# 
# Algorithm features:
# * O(N^3) complexity
# * no additional time consuming features, just triangular solver
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS:
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.cmatrixsolvefast(a, n, b)
SYNTAX: b, info = xalglib.smp_cmatrixsolvefast(a, n, b)

cmatrixsolvem function

#
# Complex dense solver for A*X=B with N*N  complex  matrix  A,  N*M  complex
# matrices  X  and  B.  "Slow-but-feature-rich"   version   which   provides
# additional functions, at the cost of slower  performance.  Faster  version
# may be invoked with CMatrixSolveMFast() function.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * iterative refinement
# * O(N^3+M*N^2) complexity
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear  system
#            ! and  performs  iterative   refinement,   which   results   in
#            ! significant performance penalty  when  compared  with  "fast"
#            ! version  which  just  performs  LU  decomposition  and  calls
#            ! triangular solver.
#            !
#            ! This  performance  penalty  is  especially  visible  in   the
#            ! multithreaded mode, because both condition number  estimation
#            ! and   iterative    refinement   are   inherently   sequential
#            ! calculations.
#            !
#            ! Thus, if you need high performance and if you are pretty sure
#            ! that your system is well conditioned, we  strongly  recommend
#            ! you to use faster solver, CMatrixSolveMFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
#     RFS     -   iterative refinement switch:
#                 * True - refinement is used.
#                   Less performance, more precision.
#                 * False - refinement is not used.
#                   More performance, less precision.
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N,M], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.cmatrixsolvem(a, n, b, m, rfs)
SYNTAX: info, rep, x = xalglib.smp_cmatrixsolvem(a, n, b, m, rfs)

cmatrixsolvemfast function

#
# Complex dense solver for A*X=B with N*N  complex  matrix  A,  N*M  complex
# matrices  X  and  B.  "Fast-but-lightweight" version which  provides  just
# triangular solver - and no additional functions like iterative  refinement
# or condition number estimation.
# 
# Algorithm features:
# * O(N^3+M*N^2) complexity
# * no additional time consuming functions
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS:
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N,M]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 16.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.cmatrixsolvemfast(a, n, b, m)
SYNTAX: b, info = xalglib.smp_cmatrixsolvemfast(a, n, b, m)

hpdmatrixcholeskysolve function

#
# Dense solver for A*x=b with N*N Hermitian positive definite matrix A given
# by its Cholesky decomposition, and N*1 complex vectors x and  b.  This  is
# "slow-but-feature-rich" version of the solver  which  estimates  condition
# number of the system.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(N^2) complexity
# * condition number estimation
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which results in 10-15x  performance  penalty  when  compared
#            ! with "fast" version which just calls triangular solver.
#            !
#            ! This performance penalty is insignificant  when compared with
#            ! cost of large LU decomposition.  However,  if you  call  this
#            ! function many times for the same  left  side,  this  overhead
#            ! BECOMES significant. It  also  becomes significant for small-
#            ! scale problems (N<50).
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! HPDMatrixCholeskySolveFast() function.
# 
# INPUT PARAMETERS
#     CHA     -   array[0..N-1,0..N-1], Cholesky decomposition,
#                 SPDMatrixCholesky result
#     N       -   size of A
#     IsUpper -   what half of CHA is provided
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or ill conditioned
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N]:
#                 * for info>0  - solution
#                 * for info=-3 - filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.hpdmatrixcholeskysolve(cha, n, isupper, b)

hpdmatrixcholeskysolvefast function

#
# Dense solver for A*x=b with N*N Hermitian positive definite matrix A given
# by its Cholesky decomposition, and N*1 complex vectors x and  b.  This  is
# "fast-but-lightweight" version of the solver.
# 
# Algorithm features:
# * O(N^2) complexity
# * matrix is represented by its upper or lower triangle
# * no additional time-consuming features
# 
# INPUT PARAMETERS
#     CHA     -   array[0..N-1,0..N-1], Cholesky decomposition,
#                 SPDMatrixCholesky result
#     N       -   size of A
#     IsUpper -   what half of CHA is provided
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or ill conditioned
#                         B is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N]:
#                 * for info>0  - overwritten by solution
#                 * for info=-3 - filled by zeros
# 
#   -- ALGLIB --
#      Copyright 18.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.hpdmatrixcholeskysolvefast(cha, n, isupper, b)

hpdmatrixcholeskysolvem function

#
# Dense solver for A*X=B with N*N Hermitian positive definite matrix A given
# by its Cholesky decomposition and N*M complex matrices X  and  B.  This is
# "slow-but-feature-rich" version of the solver which, in  addition  to  the
# solution, estimates condition number of the system.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(M*N^2) complexity
# * condition number estimation
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant  performance   penalty   when
#            ! compared with "fast"  version  which  just  calls  triangular
#            ! solver. Amount of  overhead  introduced  depends  on  M  (the
#            ! larger - the more efficient).
#            !
#            ! This performance penalty is insignificant  when compared with
#            ! cost of large Cholesky decomposition.  However,  if  you call
#            ! this  function  many  times  for  the same  left  side,  this
#            ! overhead BECOMES significant. It  also   becomes  significant
#            ! for small-scale problems (N<50).
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! HPDMatrixCholeskySolveMFast() function.
# 
# 
# INPUT PARAMETERS
#     CHA     -   array[N,N], Cholesky decomposition,
#                 HPDMatrixCholesky result
#     N       -   size of CHA
#     IsUpper -   what half of CHA is provided
#     B       -   array[N,M], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS:
#     Info    -   return code:
#                 * -3    A is singular, or VERY close to singular.
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task was solved
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N]:
#                 * for info>0 contains solution
#                 * for info=-3 filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.hpdmatrixcholeskysolvem(cha, n, isupper, b, m)
SYNTAX: info, rep, x = xalglib.smp_hpdmatrixcholeskysolvem(cha, n, isupper, b, m)

hpdmatrixcholeskysolvemfast function

#
# Dense solver for A*X=B with N*N Hermitian positive definite matrix A given
# by its Cholesky decomposition and N*M complex matrices X  and  B.  This is
# "fast-but-lightweight" version of the solver.
# 
# Algorithm features:
# * O(M*N^2) complexity
# * matrix is represented by its upper or lower triangle
# * no additional time-consuming features
# 
# INPUT PARAMETERS
#     CHA     -   array[N,N], Cholesky decomposition,
#                 HPDMatrixCholesky result
#     N       -   size of CHA
#     IsUpper -   what half of CHA is provided
#     B       -   array[N,M], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS:
#     Info    -   return code:
#                 * -3    A is singular, or VERY close to singular.
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task was solved
#     B       -   array[N]:
#                 * for info>0 overwritten by solution
#                 * for info=-3 filled by zeros
# 
#   -- ALGLIB --
#      Copyright 18.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.hpdmatrixcholeskysolvemfast(cha, n, isupper, b, m)
SYNTAX: b, info = xalglib.smp_hpdmatrixcholeskysolvemfast(cha, n, isupper, b, m)

hpdmatrixsolve function

#
# Dense solver for A*x=b, with N*N Hermitian positive definite matrix A, and
# N*1 complex vectors  x  and  b.  "Slow-but-feature-rich"  version  of  the
# solver.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * O(N^3) complexity
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant   performance   penalty  when
#            ! compared with "fast" version  which  just  performs  Cholesky
#            ! decomposition and calls triangular solver.
#            !
#            ! This  performance  penalty  is  especially  visible  in   the
#            ! multithreaded mode, because both condition number  estimation
#            ! and   iterative    refinement   are   inherently   sequential
#            ! calculations.
#            !
#            ! Thus, if you need high performance and if you are pretty sure
#            ! that your system is well conditioned, we  strongly  recommend
#            ! you to use faster solver, HPDMatrixSolveFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   same as in RMatrixSolve
#                 Returns -3 for non-HPD matrices.
#     Rep     -   same as in RMatrixSolve
#     X       -   same as in RMatrixSolve
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.hpdmatrixsolve(a, n, isupper, b)
SYNTAX: info, rep, x = xalglib.smp_hpdmatrixsolve(a, n, isupper, b)

hpdmatrixsolvefast function

#
# Dense solver for A*x=b, with N*N Hermitian positive definite matrix A, and
# N*1 complex vectors  x  and  b.  "Fast-but-lightweight"  version  of   the
# solver without additional functions.
# 
# Algorithm features:
# * O(N^3) complexity
# * matrix is represented by its upper or lower triangle
# * no additional time consuming functions
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or not positive definite
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task was solved
#     B       -   array[0..N-1]:
#                 * overwritten by solution
#                 * zeros, if A is exactly singular (diagonal of its LU
#                   decomposition has exact zeros).
# 
#   -- ALGLIB --
#      Copyright 17.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.hpdmatrixsolvefast(a, n, isupper, b)
SYNTAX: b, info = xalglib.smp_hpdmatrixsolvefast(a, n, isupper, b)

hpdmatrixsolvem function

#
# Dense solver for A*X=B, with N*N Hermitian positive definite matrix A  and
# N*M  complex  matrices  X  and  B.  "Slow-but-feature-rich" version of the
# solver.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * O(N^3+M*N^2) complexity
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant  performance   penalty   when
#            ! compared with "fast"  version  which  just  calls  triangular
#            ! solver.
#            !
#            ! This performance penalty is especially apparent when you  use
#            ! ALGLIB parallel capabilities (condition number estimation  is
#            ! inherently  sequential).  It   also   becomes significant for
#            ! small-scale problems (N<100).
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! HPDMatrixSolveMFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   same as in RMatrixSolve.
#                 Returns -3 for non-HPD matrices.
#     Rep     -   same as in RMatrixSolve
#     X       -   same as in RMatrixSolve
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.hpdmatrixsolvem(a, n, isupper, b, m)
SYNTAX: info, rep, x = xalglib.smp_hpdmatrixsolvem(a, n, isupper, b, m)

hpdmatrixsolvemfast function

#
# Dense solver for A*X=B, with N*N Hermitian positive definite matrix A  and
# N*M complex matrices X and B. "Fast-but-lightweight" version of the solver.
# 
# Algorithm features:
# * O(N^3+M*N^2) complexity
# * matrix is represented by its upper or lower triangle
# * no additional time consuming features like condition number estimation
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly  singular or is not positive definite.
#                         B is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[0..N-1]:
#                 * overwritten by solution
#                 * zeros, if problem was not solved
# 
#   -- ALGLIB --
#      Copyright 17.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.hpdmatrixsolvemfast(a, n, isupper, b, m)
SYNTAX: b, info = xalglib.smp_hpdmatrixsolvemfast(a, n, isupper, b, m)

rmatrixlusolve function

#
# Dense solver.
# 
# This  subroutine  solves  a  system  A*x=b,  where A is NxN non-denegerate
# real matrix given by its LU decomposition, x and b are real vectors.  This
# is "slow-but-robust" version of the linear LU-based solver. Faster version
# is RMatrixLUSolveFast() function.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(N^2) complexity
# * condition number estimation
# 
# No iterative refinement  is provided because exact form of original matrix
# is not known to subroutine. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which results in 10-15x  performance  penalty  when  compared
#            ! with "fast" version which just calls triangular solver.
#            !
#            ! This performance penalty is insignificant  when compared with
#            ! cost of large LU decomposition.  However,  if you  call  this
#            ! function many times for the same  left  side,  this  overhead
#            ! BECOMES significant. It  also  becomes significant for small-
#            ! scale problems.
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! RMatrixLUSolveFast() function.
# 
# INPUT PARAMETERS
#     LUA     -   array[N,N], LU decomposition, RMatrixLU result
#     P       -   array[N], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[N], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.rmatrixlusolve(lua, p, n, b)

rmatrixlusolvefast function

#
# Dense solver.
# 
# This  subroutine  solves  a  system  A*x=b,  where A is NxN non-denegerate
# real matrix given by its LU decomposition, x and b are real vectors.  This
# is "fast-without-any-checks" version of the linear LU-based solver. Slower
# but more robust version is RMatrixLUSolve() function.
# 
# Algorithm features:
# * O(N^2) complexity
# * fast algorithm without ANY additional checks, just triangular solver
# 
# INPUT PARAMETERS
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, RMatrixLU result
#     P       -   array[0..N-1], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 18.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.rmatrixlusolvefast(lua, p, n, b)

rmatrixlusolvem function

#
# Dense solver.
# 
# Similar to RMatrixLUSolve() but solves  task  with  multiple  right  parts
# (where b and x are NxM matrices). This  is  "robust-but-slow"  version  of
# LU-based solver which performs additional  checks  for  non-degeneracy  of
# inputs (condition number estimation). If you need  best  performance,  use
# "fast-without-any-checks" version, RMatrixLUSolveMFast().
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(M*N^2) complexity
# * condition number estimation
# 
# No iterative refinement  is provided because exact form of original matrix
# is not known to subroutine. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant  performance   penalty   when
#            ! compared with "fast"  version  which  just  calls  triangular
#            ! solver.
#            !
#            ! This performance penalty is especially apparent when you  use
#            ! ALGLIB parallel capabilities (condition number estimation  is
#            ! inherently  sequential).  It   also   becomes significant for
#            ! small-scale problems.
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! RMatrixLUSolveMFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. Triangular solver is relatively easy to parallelize.
#   ! However, parallelization will be efficient  only for  large number  of
#   ! right parts M.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     LUA     -   array[N,N], LU decomposition, RMatrixLU result
#     P       -   array[N], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N,M], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.rmatrixlusolvem(lua, p, n, b, m)
SYNTAX: info, rep, x = xalglib.smp_rmatrixlusolvem(lua, p, n, b, m)

rmatrixlusolvemfast function

#
# Dense solver.
# 
# Similar to RMatrixLUSolve() but solves  task  with  multiple  right parts,
# where b and x are NxM matrices.  This is "fast-without-any-checks" version
# of LU-based solver. It does not estimate  condition number  of  a  system,
# so it is extremely fast. If you need better detection  of  near-degenerate
# cases, use RMatrixLUSolveM() function.
# 
# Algorithm features:
# * O(M*N^2) complexity
# * fast algorithm without ANY additional checks, just triangular solver
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. Triangular solver is relatively easy to parallelize.
#   ! However, parallelization will be efficient  only for  large number  of
#   ! right parts M.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, RMatrixLU result
#     P       -   array[0..N-1], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS:
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N,M]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 18.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.rmatrixlusolvemfast(lua, p, n, b, m)
SYNTAX: b, info = xalglib.smp_rmatrixlusolvemfast(lua, p, n, b, m)

rmatrixmixedsolve function

#
# Dense solver.
# 
# This  subroutine  solves  a  system  A*x=b,  where BOTH ORIGINAL A AND ITS
# LU DECOMPOSITION ARE KNOWN. You can use it if for some  reasons  you  have
# both A and its LU decomposition.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * iterative refinement
# * O(N^2) complexity
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, RMatrixLU result
#     P       -   array[0..N-1], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.rmatrixmixedsolve(a, lua, p, n, b)

rmatrixmixedsolvem function

#
# Dense solver.
# 
# Similar to RMatrixMixedSolve() but  solves task with multiple right  parts
# (where b and x are NxM matrices).
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * iterative refinement
# * O(M*N^2) complexity
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     LUA     -   array[0..N-1,0..N-1], LU decomposition, RMatrixLU result
#     P       -   array[0..N-1], pivots array, RMatrixLU result
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N,M], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.rmatrixmixedsolvem(a, lua, p, n, b, m)

rmatrixsolve function

#
# Dense solver for A*x=b with N*N real matrix A and N*1 real vectorx  x  and
# b. This is "slow-but-feature rich" version of the  linear  solver.  Faster
# version is RMatrixSolveFast() function.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * iterative refinement
# * O(N^3) complexity
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear  system
#            ! and  performs  iterative   refinement,   which   results   in
#            ! significant performance penalty  when  compared  with  "fast"
#            ! version  which  just  performs  LU  decomposition  and  calls
#            ! triangular solver.
#            !
#            ! This  performance  penalty  is  especially  visible  in   the
#            ! multithreaded mode, because both condition number  estimation
#            ! and   iterative    refinement   are   inherently   sequential
#            ! calculations. It also very significant on small matrices.
#            !
#            ! Thus, if you need high performance and if you are pretty sure
#            ! that your system is well conditioned, we  strongly  recommend
#            ! you to use faster solver, RMatrixSolveFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or exactly singular.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.rmatrixsolve(a, n, b)
SYNTAX: info, rep, x = xalglib.smp_rmatrixsolve(a, n, b)

rmatrixsolvefast function

#
# Dense solver.
# 
# This  subroutine  solves  a  system  A*x=b,  where A is NxN non-denegerate
# real matrix, x  and  b  are  vectors.  This is a "fast" version of  linear
# solver which does NOT provide  any  additional  functions  like  condition
# number estimation or iterative refinement.
# 
# Algorithm features:
# * efficient algorithm O(N^3) complexity
# * no performance overhead from additional functionality
# 
# If you need condition number estimation or iterative refinement, use  more
# feature-rich version - RMatrixSolve().
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 16.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.rmatrixsolvefast(a, n, b)
SYNTAX: b, info = xalglib.smp_rmatrixsolvefast(a, n, b)

rmatrixsolvels function

#
# Dense solver.
# 
# This subroutine finds solution of the linear system A*X=B with non-square,
# possibly degenerate A.  System  is  solved in the least squares sense, and
# general least squares solution  X = X0 + CX*y  which  minimizes |A*X-B| is
# returned. If A is non-degenerate, solution in the usual sense is returned.
# 
# Algorithm features:
# * automatic detection (and correct handling!) of degenerate cases
# * iterative refinement
# * O(N^3) complexity
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes one  important  improvement   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! Multithreaded acceleration is only partially supported (some parts are
#   ! optimized, but most - are not).
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..NRows-1,0..NCols-1], system matrix
#     NRows   -   vertical size of A
#     NCols   -   horizontal size of A
#     B       -   array[0..NCols-1], right part
#     Threshold-  a number in [0,1]. Singular values  beyond  Threshold  are
#                 considered  zero.  Set  it to 0.0, if you don't understand
#                 what it means, so the solver will choose good value on its
#                 own.
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -4    SVD subroutine failed
#                 * -1    if NRows<=0 or NCols<=0 or Threshold<0 was passed
#                 *  1    if task is solved
#     Rep     -   solver report, see below for more info
#     X       -   array[0..N-1,0..M-1], it contains:
#                 * solution of A*X=B (even for singular A)
#                 * zeros, if SVD subroutine failed
# 
# SOLVER REPORT
# 
# Subroutine sets following fields of the Rep structure:
# * R2        reciprocal of condition number: 1/cond(A), 2-norm.
# * N         = NCols
# * K         dim(Null(A))
# * CX        array[0..N-1,0..K-1], kernel of A.
#             Columns of CX store such vectors that A*CX[i]=0.
# 
#   -- ALGLIB --
#      Copyright 24.08.2009 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.rmatrixsolvels(a, nrows, ncols, b, threshold)
SYNTAX: info, rep, x = xalglib.smp_rmatrixsolvels(a, nrows, ncols, b, threshold)

rmatrixsolvem function

#
# Dense solver.
# 
# Similar to RMatrixSolve() but solves task with multiple right parts (where
# b and x are NxM matrices). This is  "slow-but-robust"  version  of  linear
# solver with additional functionality  like  condition  number  estimation.
# There also exists faster version - RMatrixSolveMFast().
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * optional iterative refinement
# * O(N^3+M*N^2) complexity
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear  system
#            ! and  performs  iterative   refinement,   which   results   in
#            ! significant performance penalty  when  compared  with  "fast"
#            ! version  which  just  performs  LU  decomposition  and  calls
#            ! triangular solver.
#            !
#            ! This  performance  penalty  is  especially  visible  in   the
#            ! multithreaded mode, because both condition number  estimation
#            ! and   iterative    refinement   are   inherently   sequential
#            ! calculations. It also very significant on small matrices.
#            !
#            ! Thus, if you need high performance and if you are pretty sure
#            ! that your system is well conditioned, we  strongly  recommend
#            ! you to use faster solver, RMatrixSolveMFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
#     RFS     -   iterative refinement switch:
#                 * True - refinement is used.
#                   Less performance, more precision.
#                 * False - refinement is not used.
#                   More performance, less precision.
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is ill conditioned or singular.
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.rmatrixsolvem(a, n, b, m, rfs)
SYNTAX: info, rep, x = xalglib.smp_rmatrixsolvem(a, n, b, m, rfs)

rmatrixsolvemfast function

#
# Dense solver.
# 
# Similar to RMatrixSolve() but solves task with multiple right parts (where
# b and x are NxM matrices). This is "fast" version of linear  solver  which
# does NOT offer additional functions like condition  number  estimation  or
# iterative refinement.
# 
# Algorithm features:
# * O(N^3+M*N^2) complexity
# * no additional functionality, highest performance
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that LU decomposition  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
#     RFS     -   iterative refinement switch:
#                 * True - refinement is used.
#                   Less performance, more precision.
#                 * False - refinement is not used.
#                   More performance, less precision.
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is exactly singular (ill conditioned matrices
#                         are not recognized).
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     B       -   array[N]:
#                 * info>0    =>  overwritten by solution
#                 * info=-3   =>  filled by zeros
# 
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.rmatrixsolvemfast(a, n, b, m)
SYNTAX: b, info = xalglib.smp_rmatrixsolvemfast(a, n, b, m)

spdmatrixcholeskysolve function

#
# Dense solver for A*x=b with N*N symmetric positive definite matrix A given
# by its Cholesky decomposition, and N*1 real vectors x and b. This is "slow-
# but-feature-rich"  version  of  the  solver  which,  in  addition  to  the
# solution, performs condition number estimation.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(N^2) complexity
# * condition number estimation
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which results in 10-15x  performance  penalty  when  compared
#            ! with "fast" version which just calls triangular solver.
#            !
#            ! This performance penalty is insignificant  when compared with
#            ! cost of large LU decomposition.  However,  if you  call  this
#            ! function many times for the same  left  side,  this  overhead
#            ! BECOMES significant. It  also  becomes significant for small-
#            ! scale problems (N<50).
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! SPDMatrixCholeskySolveFast() function.
# 
# INPUT PARAMETERS
#     CHA     -   array[N,N], Cholesky decomposition,
#                 SPDMatrixCholesky result
#     N       -   size of A
#     IsUpper -   what half of CHA is provided
#     B       -   array[N], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or ill conditioned
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N]:
#                 * for info>0  - solution
#                 * for info=-3 - filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.spdmatrixcholeskysolve(cha, n, isupper, b)

spdmatrixcholeskysolvefast function

#
# Dense solver for A*x=b with N*N symmetric positive definite matrix A given
# by its Cholesky decomposition, and N*1 real vectors x and b. This is "fast-
# but-lightweight" version of the solver.
# 
# Algorithm features:
# * O(N^2) complexity
# * matrix is represented by its upper or lower triangle
# * no additional features
# 
# INPUT PARAMETERS
#     CHA     -   array[N,N], Cholesky decomposition,
#                 SPDMatrixCholesky result
#     N       -   size of A
#     IsUpper -   what half of CHA is provided
#     B       -   array[N], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or ill conditioned
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task is solved
#     B       -   array[N]:
#                 * for info>0  - overwritten by solution
#                 * for info=-3 - filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.spdmatrixcholeskysolvefast(cha, n, isupper, b)

spdmatrixcholeskysolvem function

#
# Dense solver for A*X=B with N*N symmetric positive definite matrix A given
# by its Cholesky decomposition, and N*M vectors X and B. It  is  "slow-but-
# feature-rich" version of the solver which estimates  condition  number  of
# the system.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * O(M*N^2) complexity
# * condition number estimation
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant  performance   penalty   when
#            ! compared with "fast"  version  which  just  calls  triangular
#            ! solver. Amount of  overhead  introduced  depends  on  M  (the
#            ! larger - the more efficient).
#            !
#            ! This performance penalty is insignificant  when compared with
#            ! cost of large LU decomposition.  However,  if you  call  this
#            ! function many times for the same  left  side,  this  overhead
#            ! BECOMES significant. It  also  becomes significant for small-
#            ! scale problems (N<50).
#            !
#            ! In such cases we strongly recommend you to use faster solver,
#            ! SPDMatrixCholeskySolveMFast() function.
# 
# INPUT PARAMETERS
#     CHA     -   array[0..N-1,0..N-1], Cholesky decomposition,
#                 SPDMatrixCholesky result
#     N       -   size of CHA
#     IsUpper -   what half of CHA is provided
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or badly conditioned
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task was solved
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N]:
#                 * for info>0 contains solution
#                 * for info=-3 filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.spdmatrixcholeskysolvem(cha, n, isupper, b, m)
SYNTAX: info, rep, x = xalglib.smp_spdmatrixcholeskysolvem(cha, n, isupper, b, m)

spdmatrixcholeskysolvemfast function

#
# Dense solver for A*X=B with N*N symmetric positive definite matrix A given
# by its Cholesky decomposition, and N*M vectors X and B. It  is  "fast-but-
# lightweight" version of  the  solver  which  just  solves  linear  system,
# without any additional functions.
# 
# Algorithm features:
# * O(M*N^2) complexity
# * matrix is represented by its upper or lower triangle
# * no additional functionality
# 
# INPUT PARAMETERS
#     CHA     -   array[N,N], Cholesky decomposition,
#                 SPDMatrixCholesky result
#     N       -   size of CHA
#     IsUpper -   what half of CHA is provided
#     B       -   array[N,M], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or badly conditioned
#                         X is filled by zeros in such cases.
#                 * -1    N<=0 was passed
#                 *  1    task was solved
#     B       -   array[N]:
#                 * for info>0 overwritten by solution
#                 * for info=-3 filled by zeros
# 
#   -- ALGLIB --
#      Copyright 18.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.spdmatrixcholeskysolvemfast(cha, n, isupper, b, m)
SYNTAX: b, info = xalglib.smp_spdmatrixcholeskysolvemfast(cha, n, isupper, b, m)

spdmatrixsolve function

#
# Dense linear solver for A*x=b with N*N real  symmetric  positive  definite
# matrix A,  N*1 vectors x and b.  "Slow-but-feature-rich"  version  of  the
# solver.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * O(N^3) complexity
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant   performance   penalty  when
#            ! compared with "fast" version  which  just  performs  Cholesky
#            ! decomposition and calls triangular solver.
#            !
#            ! This  performance  penalty  is  especially  visible  in   the
#            ! multithreaded mode, because both condition number  estimation
#            ! and   iterative    refinement   are   inherently   sequential
#            ! calculations.
#            !
#            ! Thus, if you need high performance and if you are pretty sure
#            ! that your system is well conditioned, we  strongly  recommend
#            ! you to use faster solver, SPDMatrixSolveFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or non-SPD.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.spdmatrixsolve(a, n, isupper, b)
SYNTAX: info, rep, x = xalglib.smp_spdmatrixsolve(a, n, isupper, b)

spdmatrixsolvefast function

#
# Dense linear solver for A*x=b with N*N real  symmetric  positive  definite
# matrix A,  N*1 vectors x and  b.  "Fast-but-lightweight"  version  of  the
# solver.
# 
# Algorithm features:
# * O(N^3) complexity
# * matrix is represented by its upper or lower triangle
# * no additional time consuming features like condition number estimation
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1], right part
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular or non-SPD
#                 * -1    N<=0 was passed
#                 *  1    task was solved
#     B       -   array[N], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 17.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.spdmatrixsolvefast(a, n, isupper, b)
SYNTAX: b, info = xalglib.smp_spdmatrixsolvefast(a, n, isupper, b)

spdmatrixsolvem function

#
# Dense solver for A*X=B with N*N symmetric positive definite matrix A,  and
# N*M vectors X and B. It is "slow-but-feature-rich" version of the solver.
# 
# Algorithm features:
# * automatic detection of degenerate cases
# * condition number estimation
# * O(N^3+M*N^2) complexity
# * matrix is represented by its upper or lower triangle
# 
# No iterative refinement is provided because such partial representation of
# matrix does not allow efficient calculation of extra-precise  matrix-vector
# products for large matrices. Use RMatrixSolve or RMatrixMixedSolve  if  you
# need iterative refinement.
# 
# IMPORTANT: ! this function is NOT the most efficient linear solver provided
#            ! by ALGLIB. It estimates condition  number  of  linear system,
#            ! which  results  in  significant   performance   penalty  when
#            ! compared with "fast" version  which  just  performs  Cholesky
#            ! decomposition and calls triangular solver.
#            !
#            ! This  performance  penalty  is  especially  visible  in   the
#            ! multithreaded mode, because both condition number  estimation
#            ! and   iterative    refinement   are   inherently   sequential
#            ! calculations.
#            !
#            ! Thus, if you need high performance and if you are pretty sure
#            ! that your system is well conditioned, we  strongly  recommend
#            ! you to use faster solver, SPDMatrixSolveMFast() function.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    matrix is very badly conditioned or non-SPD.
#                 * -1    N<=0 was passed
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   additional report, following fields are set:
#                 * rep.r1    condition number in 1-norm
#                 * rep.rinf  condition number in inf-norm
#     X       -   array[N,M], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 27.01.2010 by Bochkanov Sergey
#

SYNTAX: info, rep, x = xalglib.spdmatrixsolvem(a, n, isupper, b, m)
SYNTAX: info, rep, x = xalglib.smp_spdmatrixsolvem(a, n, isupper, b, m)

spdmatrixsolvemfast function

#
# Dense solver for A*X=B with N*N symmetric positive definite matrix A,  and
# N*M vectors X and B. It is "fast-but-lightweight" version of the solver.
# 
# Algorithm features:
# * O(N^3+M*N^2) complexity
# * matrix is represented by its upper or lower triangle
# * no additional time consuming features
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that Cholesky decomposition is harder
#   ! to parallelize than, say, matrix-matrix product - this  algorithm  has
#   ! several synchronization points which  can  not  be  avoided.  However,
#   ! parallelism starts to be profitable starting from N=500.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS
#     A       -   array[0..N-1,0..N-1], system matrix
#     N       -   size of A
#     IsUpper -   what half of A is provided
#     B       -   array[0..N-1,0..M-1], right part
#     M       -   right part size
# 
# OUTPUT PARAMETERS
#     Info    -   return code:
#                 * -3    A is is exactly singular
#                 * -1    N<=0 was passed
#                 *  1    task was solved
#     B       -   array[N,M], it contains:
#                 * info>0    =>  solution
#                 * info=-3   =>  filled by zeros
# 
#   -- ALGLIB --
#      Copyright 17.03.2015 by Bochkanov Sergey
#

SYNTAX: b, info = xalglib.spdmatrixsolvemfast(a, n, isupper, b, m)
SYNTAX: b, info = xalglib.smp_spdmatrixsolvemfast(a, n, isupper, b, m)

dforest module

decisionforest class

#
# 
#

class decisionforest(object):
    ...

dfreport class

#
# 
#

class dfreport(object):
    ...

dfavgce function

#
# Average cross-entropy (in bits per element) on the test set
# 
# INPUT PARAMETERS:
#     DF      -   decision forest model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     CrossEntropy/(NPoints*LN(2)).
#     Zero if model solves regression task.
# 
#   -- ALGLIB --
#      Copyright 16.02.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.dfavgce(df, xy, npoints)

dfavgerror function

#
# Average error on the test set
# 
# INPUT PARAMETERS:
#     DF      -   decision forest model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     Its meaning for regression task is obvious. As for
#     classification task, it means average error when estimating posterior
#     probabilities.
# 
#   -- ALGLIB --
#      Copyright 16.02.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.dfavgerror(df, xy, npoints)

dfavgrelerror function

#
# Average relative error on the test set
# 
# INPUT PARAMETERS:
#     DF      -   decision forest model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     Its meaning for regression task is obvious. As for
#     classification task, it means average relative error when estimating
#     posterior probability of belonging to the correct class.
# 
#   -- ALGLIB --
#      Copyright 16.02.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.dfavgrelerror(df, xy, npoints)

dfbuildrandomdecisionforest function

#
# This subroutine builds random decision forest.
# 
# INPUT PARAMETERS:
#     XY          -   training set
#     NPoints     -   training set size, NPoints>=1
#     NVars       -   number of independent variables, NVars>=1
#     NClasses    -   task type:
#                     * NClasses=1 - regression task with one
#                                    dependent variable
#                     * NClasses>1 - classification task with
#                                    NClasses classes.
#     NTrees      -   number of trees in a forest, NTrees>=1.
#                     recommended values: 50-100.
#     R           -   percent of a training set used to build
#                     individual trees. 0<R<=1.
#                     recommended values: 0.1 <= R <= 0.66.
# 
# OUTPUT PARAMETERS:
#     Info        -   return code:
#                     * -2, if there is a point with class number
#                           outside of [0..NClasses-1].
#                     * -1, if incorrect parameters was passed
#                           (NPoints<1, NVars<1, NClasses<1, NTrees<1, R<=0
#                           or R>1).
#                     *  1, if task has been solved
#     DF          -   model built
#     Rep         -   training report, contains error on a training set
#                     and out-of-bag estimates of generalization error.
# 
#   -- ALGLIB --
#      Copyright 19.02.2009 by Bochkanov Sergey
#

SYNTAX: info, df, rep = xalglib.dfbuildrandomdecisionforest(xy, npoints, nvars, nclasses, ntrees, r)

dfbuildrandomdecisionforestx1 function

#
# This subroutine builds random decision forest.
# This function gives ability to tune number of variables used when choosing
# best split.
# 
# INPUT PARAMETERS:
#     XY          -   training set
#     NPoints     -   training set size, NPoints>=1
#     NVars       -   number of independent variables, NVars>=1
#     NClasses    -   task type:
#                     * NClasses=1 - regression task with one
#                                    dependent variable
#                     * NClasses>1 - classification task with
#                                    NClasses classes.
#     NTrees      -   number of trees in a forest, NTrees>=1.
#                     recommended values: 50-100.
#     NRndVars    -   number of variables used when choosing best split
#     R           -   percent of a training set used to build
#                     individual trees. 0<R<=1.
#                     recommended values: 0.1 <= R <= 0.66.
# 
# OUTPUT PARAMETERS:
#     Info        -   return code:
#                     * -2, if there is a point with class number
#                           outside of [0..NClasses-1].
#                     * -1, if incorrect parameters was passed
#                           (NPoints<1, NVars<1, NClasses<1, NTrees<1, R<=0
#                           or R>1).
#                     *  1, if task has been solved
#     DF          -   model built
#     Rep         -   training report, contains error on a training set
#                     and out-of-bag estimates of generalization error.
# 
#   -- ALGLIB --
#      Copyright 19.02.2009 by Bochkanov Sergey
#

SYNTAX: info, df, rep = xalglib.dfbuildrandomdecisionforestx1(xy, npoints, nvars, nclasses, ntrees, nrndvars, r)

dfprocess function

#
# Procesing
# 
# INPUT PARAMETERS:
#     DF      -   decision forest model
#     X       -   input vector,  array[0..NVars-1].
# 
# OUTPUT PARAMETERS:
#     Y       -   result. Regression estimate when solving regression  task,
#                 vector of posterior probabilities for classification task.
# 
# See also DFProcessI.
# 
#   -- ALGLIB --
#      Copyright 16.02.2009 by Bochkanov Sergey
#

SYNTAX: y = xalglib.dfprocess(df, x, y)

dfprocessi function

#
# 'interactive' variant of DFProcess for languages like Python which support
# constructs like "Y = DFProcessI(DF,X)" and interactive mode of interpreter
# 
# This function allocates new array on each call,  so  it  is  significantly
# slower than its 'non-interactive' counterpart, but it is  more  convenient
# when you call it from command line.
# 
#   -- ALGLIB --
#      Copyright 28.02.2010 by Bochkanov Sergey
#

SYNTAX: y = xalglib.dfprocessi(df, x)

dfrelclserror function

#
# Relative classification error on the test set
# 
# INPUT PARAMETERS:
#     DF      -   decision forest model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     percent of incorrectly classified cases.
#     Zero if model solves regression task.
# 
#   -- ALGLIB --
#      Copyright 16.02.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.dfrelclserror(df, xy, npoints)

dfrmserror function

#
# RMS error on the test set
# 
# INPUT PARAMETERS:
#     DF      -   decision forest model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     root mean square error.
#     Its meaning for regression task is obvious. As for
#     classification task, RMS error means error when estimating posterior
#     probabilities.
# 
#   -- ALGLIB --
#      Copyright 16.02.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.dfrmserror(df, xy, npoints)

dfserialize function

#
# This function serializes data structure to string.
# 
# Important properties of s_out:
# * it contains alphanumeric characters, dots, underscores, minus signs
# * these symbols are grouped into words, which are separated by spaces
#   and Windows-style (CR+LF) newlines
# * although  serializer  uses  spaces and CR+LF as separators, you can 
#   replace any separator character by arbitrary combination of spaces,
#   tabs, Windows or Unix newlines. It allows flexible reformatting  of
#   the  string  in  case you want to include it into text or XML file. 
#   But you should not insert separators into the middle of the "words"
#   nor you should change case of letters.
# * s_out can be freely moved between 32-bit and 64-bit systems, little
#   and big endian machines, and so on. You can serialize structure  on
#   32-bit machine and unserialize it on 64-bit one (or vice versa), or
#   serialize  it  on  SPARC  and  unserialize  on  x86.  You  can also 
#   serialize  it  in  C++ version of ALGLIB and unserialize in C# one, 
#   and vice versa.
#

def dfserialize(obj):

dfunserialize function

#
# This function unserializes data structure from string.
#

def dfunserialize(s_in):

elliptic module

ellipticintegrale function

#
# Complete elliptic integral of the second kind
# 
# Approximates the integral
# 
# 
#            pi/2
#             -
#            | |                 2
# E(m)  =    |    sqrt( 1 - m sin t ) dt
#          | |
#           -
#            0
# 
# using the approximation
# 
#      P(x)  -  x log x Q(x).
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE       0, 1       10000       2.1e-16     7.3e-17
# 
# Cephes Math Library, Release 2.8: June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.ellipticintegrale(m)

ellipticintegralk function

#
# Complete elliptic integral of the first kind
# 
# Approximates the integral
# 
# 
# 
#            pi/2
#             -
#            | |
#            |           dt
# K(m)  =    |    ------------------
#            |                   2
#          | |    sqrt( 1 - m sin t )
#           -
#            0
# 
# using the approximation
# 
#     P(x)  -  log x Q(x).
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE       0,1        30000       2.5e-16     6.8e-17
# 
# Cephes Math Library, Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.ellipticintegralk(m)

ellipticintegralkhighprecision function

#
# Complete elliptic integral of the first kind
# 
# Approximates the integral
# 
# 
# 
#            pi/2
#             -
#            | |
#            |           dt
# K(m)  =    |    ------------------
#            |                   2
#          | |    sqrt( 1 - m sin t )
#           -
#            0
# 
# where m = 1 - m1, using the approximation
# 
#     P(x)  -  log x Q(x).
# 
# The argument m1 is used rather than m so that the logarithmic
# singularity at m = 1 will be shifted to the origin; this
# preserves maximum accuracy.
# 
# K(0) = pi/2.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE       0,1        30000       2.5e-16     6.8e-17
# 
# Cephes Math Library, Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.ellipticintegralkhighprecision(m1)

incompleteellipticintegrale function

#
# Incomplete elliptic integral of the second kind
# 
# Approximates the integral
# 
# 
#                phi
#                 -
#                | |
#                |                   2
# E(phi_\m)  =    |    sqrt( 1 - m sin t ) dt
#                |
#              | |
#               -
#                0
# 
# of amplitude phi and modulus m, using the arithmetic -
# geometric mean algorithm.
# 
# ACCURACY:
# 
# Tested at random arguments with phi in [-10, 10] and m in
# [0, 1].
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE     -10,10      150000       3.3e-15     1.4e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1993, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.incompleteellipticintegrale(phi, m)

incompleteellipticintegralk function

#
# Incomplete elliptic integral of the first kind F(phi|m)
# 
# Approximates the integral
# 
# 
# 
#                phi
#                 -
#                | |
#                |           dt
# F(phi_\m)  =    |    ------------------
#                |                   2
#              | |    sqrt( 1 - m sin t )
#               -
#                0
# 
# of amplitude phi and modulus m, using the arithmetic -
# geometric mean algorithm.
# 
# 
# 
# 
# ACCURACY:
# 
# Tested at random points with m in [0, 1] and phi as indicated.
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE     -10,10       200000      7.4e-16     1.0e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.incompleteellipticintegralk(phi, m)

evd module

eigsubspacereport class

#
# This object stores state of the subspace iteration algorithm.
# 
# You should use ALGLIB functions to work with this object.
#

class eigsubspacereport(object):
    ...

eigsubspacestate class

#
# This object stores state of the subspace iteration algorithm.
# 
# You should use ALGLIB functions to work with this object.
#

class eigsubspacestate(object):
    ...

eigsubspacecreate function

#
# This function initializes subspace iteration solver. This solver  is  used
# to solve symmetric real eigenproblems where just a few (top K) eigenvalues
# and corresponding eigenvectors is required.
# 
# This solver can be significantly faster than  complete  EVD  decomposition
# in the following case:
# * when only just a small fraction  of  top  eigenpairs  of dense matrix is
#   required. When K approaches N, this solver is slower than complete dense
#   EVD
# * when problem matrix is sparse (and/or is not known explicitly, i.e. only
#   matrix-matrix product can be performed)
# 
# USAGE (explicit dense/sparse matrix):
# 1. User initializes algorithm state with eigsubspacecreate() call
# 2. [optional] User tunes solver parameters by calling eigsubspacesetcond()
#    or other functions
# 3. User  calls  eigsubspacesolvedense() or eigsubspacesolvesparse() methods,
#    which take algorithm state and 2D array or alglib.sparsematrix object.
# 
# USAGE (out-of-core mode):
# 1. User initializes algorithm state with eigsubspacecreate() call
# 2. [optional] User tunes solver parameters by calling eigsubspacesetcond()
#    or other functions
# 3. User activates out-of-core mode of  the  solver  and  repeatedly  calls
#    communication functions in a loop like below:
#    > alglib.eigsubspaceoocstart(state)
#    > while alglib.eigsubspaceooccontinue(state) do
#    >     alglib.eigsubspaceoocgetrequestinfo(state, out RequestType, out M)
#    >     alglib.eigsubspaceoocgetrequestdata(state, out X)
#    >     [calculate  Y=A*X, with X=R^NxM]
#    >     alglib.eigsubspaceoocsendresult(state, in Y)
#    > alglib.eigsubspaceoocstop(state, out W, out Z, out Report)
# 
# 
# INPUT PARAMETERS:
#     N       -   problem dimensionality, N>0
#     K       -   number of top eigenvector to calculate, 0<K<=N.
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: state = xalglib.eigsubspacecreate(n, k)

eigsubspacecreatebuf function

#
# Buffered version of constructor which aims to reuse  previously  allocated
# memory as much as possible.
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: xalglib.eigsubspacecreatebuf(n, k, state)

eigsubspaceooccontinue function

#
# This function performs subspace iteration  in  the  out-of-core  mode.  It
# should be used in conjunction with other out-of-core-related functions  of
# this subspackage in a loop like below:
# 
# > alglib.eigsubspaceoocstart(state)
# > while alglib.eigsubspaceooccontinue(state) do
# >     alglib.eigsubspaceoocgetrequestinfo(state, out RequestType, out M)
# >     alglib.eigsubspaceoocgetrequestdata(state, out X)
# >     [calculate  Y=A*X, with X=R^NxM]
# >     alglib.eigsubspaceoocsendresult(state, in Y)
# > alglib.eigsubspaceoocstop(state, out W, out Z, out Report)
# 
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: result = xalglib.eigsubspaceooccontinue(state)

eigsubspaceoocgetrequestdata function

#
# This function is used to retrieve information  about  out-of-core  request
# sent by solver to user code: matrix X (array[N,RequestSize) which have  to
# be multiplied by out-of-core matrix A in a product A*X.
# 
# This function returns just request data; in order to get size of  the data
# prior to processing requestm, use eigsubspaceoocgetrequestinfo().
# 
# It should be used in conjunction with other out-of-core-related  functions
# of this subspackage in a loop like below:
# 
# > alglib.eigsubspaceoocstart(state)
# > while alglib.eigsubspaceooccontinue(state) do
# >     alglib.eigsubspaceoocgetrequestinfo(state, out RequestType, out M)
# >     alglib.eigsubspaceoocgetrequestdata(state, out X)
# >     [calculate  Y=A*X, with X=R^NxM]
# >     alglib.eigsubspaceoocsendresult(state, in Y)
# > alglib.eigsubspaceoocstop(state, out W, out Z, out Report)
# 
# INPUT PARAMETERS:
#     State           -   solver running in out-of-core mode
#     X               -   possibly  preallocated   storage;  reallocated  if
#                         needed, left unchanged, if large enough  to  store
#                         request data.
# 
# OUTPUT PARAMETERS:
#     X               -   array[N,RequestSize] or larger, leading  rectangle
#                         is filled with dense matrix X.
# 
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: x = xalglib.eigsubspaceoocgetrequestdata(state, x)

eigsubspaceoocgetrequestinfo function

#
# This function is used to retrieve information  about  out-of-core  request
# sent by solver to user code: request type (current version  of  the solver
# sends only requests for matrix-matrix products) and request size (size  of
# the matrices being multiplied).
# 
# This function returns just request metrics; in order  to  get contents  of
# the matrices being multiplied, use eigsubspaceoocgetrequestdata().
# 
# It should be used in conjunction with other out-of-core-related  functions
# of this subspackage in a loop like below:
# 
# > alglib.eigsubspaceoocstart(state)
# > while alglib.eigsubspaceooccontinue(state) do
# >     alglib.eigsubspaceoocgetrequestinfo(state, out RequestType, out M)
# >     alglib.eigsubspaceoocgetrequestdata(state, out X)
# >     [calculate  Y=A*X, with X=R^NxM]
# >     alglib.eigsubspaceoocsendresult(state, in Y)
# > alglib.eigsubspaceoocstop(state, out W, out Z, out Report)
# 
# INPUT PARAMETERS:
#     State           -   solver running in out-of-core mode
# 
# OUTPUT PARAMETERS:
#     RequestType     -   type of the request to process:
#                         * 0 - for matrix-matrix product A*X, with A  being
#                           NxN matrix whose eigenvalues/vectors are needed,
#                           and X being NxREQUESTSIZE one which is  returned
#                           by the eigsubspaceoocgetrequestdata().
#     RequestSize     -   size of the X matrix (number of columns),  usually
#                         it is several times larger than number of  vectors
#                         K requested by user.
# 
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: requesttype, requestsize = xalglib.eigsubspaceoocgetrequestinfo(state)

eigsubspaceoocsendresult function

#
# This function is used to send user reply to out-of-core  request  sent  by
# solver. Usually it is product A*X for returned by solver matrix X.
# 
# It should be used in conjunction with other out-of-core-related  functions
# of this subspackage in a loop like below:
# 
# > alglib.eigsubspaceoocstart(state)
# > while alglib.eigsubspaceooccontinue(state) do
# >     alglib.eigsubspaceoocgetrequestinfo(state, out RequestType, out M)
# >     alglib.eigsubspaceoocgetrequestdata(state, out X)
# >     [calculate  Y=A*X, with X=R^NxM]
# >     alglib.eigsubspaceoocsendresult(state, in Y)
# > alglib.eigsubspaceoocstop(state, out W, out Z, out Report)
# 
# INPUT PARAMETERS:
#     State           -   solver running in out-of-core mode
#     AX              -   array[N,RequestSize] or larger, leading  rectangle
#                         is filled with product A*X.
# 
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: xalglib.eigsubspaceoocsendresult(state, ax)

eigsubspaceoocstart function

#
# This  function  initiates  out-of-core  mode  of  subspace eigensolver. It
# should be used in conjunction with other out-of-core-related functions  of
# this subspackage in a loop like below:
# 
# > alglib.eigsubspaceoocstart(state)
# > while alglib.eigsubspaceooccontinue(state) do
# >     alglib.eigsubspaceoocgetrequestinfo(state, out RequestType, out M)
# >     alglib.eigsubspaceoocgetrequestdata(state, out X)
# >     [calculate  Y=A*X, with X=R^NxM]
# >     alglib.eigsubspaceoocsendresult(state, in Y)
# > alglib.eigsubspaceoocstop(state, out W, out Z, out Report)
# 
# INPUT PARAMETERS:
#     State       -   solver object
#     MType       -   matrix type:
#                     * 0 for real  symmetric  matrix  (solver  assumes that
#                       matrix  being   processed  is  symmetric;  symmetric
#                       direct eigensolver is used for  smaller  subproblems
#                       arising during solution of larger "full" task)
#                     Future versions of ALGLIB may  introduce  support  for
#                     other  matrix   types;   for   now,   only   symmetric
#                     eigenproblems are supported.
# 
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: xalglib.eigsubspaceoocstart(state, mtype)

eigsubspaceoocstop function

#
# This  function  finalizes out-of-core  mode  of  subspace eigensolver.  It
# should be used in conjunction with other out-of-core-related functions  of
# this subspackage in a loop like below:
# 
# > alglib.eigsubspaceoocstart(state)
# > while alglib.eigsubspaceooccontinue(state) do
# >     alglib.eigsubspaceoocgetrequestinfo(state, out RequestType, out M)
# >     alglib.eigsubspaceoocgetrequestdata(state, out X)
# >     [calculate  Y=A*X, with X=R^NxM]
# >     alglib.eigsubspaceoocsendresult(state, in Y)
# > alglib.eigsubspaceoocstop(state, out W, out Z, out Report)
# 
# INPUT PARAMETERS:
#     State       -   solver state
# 
# OUTPUT PARAMETERS:
#     W           -   array[K], depending on solver settings:
#                     * top  K  eigenvalues ordered  by  descending   -   if
#                       eigenvectors are returned in Z
#                     * zeros - if invariant subspace is returned in Z
#     Z           -   array[N,K], depending on solver settings either:
#                     * matrix of eigenvectors found
#                     * orthogonal basis of K-dimensional invariant subspace
#     Rep         -   report with additional parameters
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: w, z, rep = xalglib.eigsubspaceoocstop(state)

eigsubspacesetcond function

#
# This function sets stopping critera for the solver:
# * error in eigenvector/value allowed by solver
# * maximum number of iterations to perform
# 
# INPUT PARAMETERS:
#     State       -   solver structure
#     Eps         -   eps>=0,  with non-zero value used to tell solver  that
#                     it can  stop  after  all  eigenvalues  converged  with
#                     error  roughly  proportional  to  eps*MAX(LAMBDA_MAX),
#                     where LAMBDA_MAX is a maximum eigenvalue.
#                     Zero  value  means  that  no  check  for  precision is
#                     performed.
#     MaxIts      -   maxits>=0,  with non-zero value used  to  tell  solver
#                     that it can stop after maxits  steps  (no  matter  how
#                     precise current estimate is)
# 
# NOTE: passing  eps=0  and  maxits=0  results  in  automatic  selection  of
#       moderate eps as stopping criteria (1.0E-6 in current implementation,
#       but it may change without notice).
# 
# NOTE: very small values of eps are possible (say, 1.0E-12),  although  the
#       larger problem you solve (N and/or K), the  harder  it  is  to  find
#       precise eigenvectors because rounding errors tend to accumulate.
# 
# NOTE: passing non-zero eps results in  some performance  penalty,  roughly
#       equal to 2N*(2K)^2 FLOPs per iteration. These additional computations
#       are required in order to estimate current error in  eigenvalues  via
#       Rayleigh-Ritz process.
#       Most of this additional time is  spent  in  construction  of  ~2Kx2K
#       symmetric  subproblem  whose  eigenvalues  are  checked  with  exact
#       eigensolver.
#       This additional time is negligible if you search for eigenvalues  of
#       the large dense matrix, but may become noticeable on  highly  sparse
#       EVD problems, where cost of matrix-matrix product is low.
#       If you set eps to exactly zero,  Rayleigh-Ritz  phase  is completely
#       turned off.
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: xalglib.eigsubspacesetcond(state, eps, maxits)

eigsubspacesolvedenses function

#
# This  function runs eigensolver for dense NxN symmetric matrix A, given by
# upper or lower triangle.
# 
# This function can not process nonsymmetric matrices.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * multithreading support
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   !
#   ! For a situation  when  you  need  just  a  few  eigenvectors  (~1-10),
#   ! multithreading typically gives sublinear (wrt to cores count) speedup.
#   ! For larger  problems  it  may  give  you  nearly  linear  increase  in
#   ! performance.
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison. Best results are achieved  for  high-dimensional  problems
#   ! (NVars is at least 256).
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     State       -   solver state
#     A           -   array[N,N], symmetric NxN matrix given by one  of  its
#                     triangles
#     IsUpper     -   whether upper or lower triangle of  A  is  given  (the
#                     other one is not referenced at all).
# 
# OUTPUT PARAMETERS:
#     W           -   array[K], top  K  eigenvalues ordered  by   descending
#                     of their absolute values
#     Z           -   array[N,K], matrix of eigenvectors found
#     Rep         -   report with additional parameters
# 
# NOTE: internally this function allocates a copy of NxN dense A. You should
#       take it into account when working with very large matrices occupying
#       almost all RAM.
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: w, z, rep = xalglib.eigsubspacesolvedenses(state, a, isupper)
SYNTAX: w, z, rep = xalglib.smp_eigsubspacesolvedenses(state, a, isupper)

eigsubspacesolvesparses function

#
# This  function runs eigensolver for dense NxN symmetric matrix A, given by
# upper or lower triangle.
# 
# This function can not process nonsymmetric matrices.
# 
# INPUT PARAMETERS:
#     State       -   solver state
#     A           -   NxN symmetric matrix given by one of its triangles
#     IsUpper     -   whether upper or lower triangle of  A  is  given  (the
#                     other one is not referenced at all).
# 
# OUTPUT PARAMETERS:
#     W           -   array[K], top  K  eigenvalues ordered  by   descending
#                     of their absolute values
#     Z           -   array[N,K], matrix of eigenvectors found
#     Rep         -   report with additional parameters
# 
#   -- ALGLIB --
#      Copyright 16.01.2017 by Bochkanov Sergey
#

SYNTAX: w, z, rep = xalglib.eigsubspacesolvesparses(state, a, isupper)

hmatrixevd function

#
# Finding the eigenvalues and eigenvectors of a Hermitian matrix
# 
# The algorithm finds eigen pairs of a Hermitian matrix by  reducing  it  to
# real tridiagonal form and using the QL/QR algorithm.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes one  important  improvement   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! Multithreaded acceleration is NOT supported for this function.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   Hermitian matrix which is given  by  its  upper  or  lower
#                 triangular part.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     IsUpper -   storage format.
#     ZNeeded -   flag controlling whether the eigenvectors  are  needed  or
#                 not. If ZNeeded is equal to:
#                  * 0, the eigenvectors are not returned;
#                  * 1, the eigenvectors are returned.
# 
# Output parameters:
#     D       -   eigenvalues in ascending order.
#                 Array whose index ranges within [0..N-1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z hasn't changed;
#                  * 1, Z contains the eigenvectors.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#                 The eigenvectors are stored in the matrix columns.
# 
# Result:
#     True, if the algorithm has converged.
#     False, if the algorithm hasn't converged (rare case).
# 
# Note:
#     eigenvectors of Hermitian matrix are defined up to  multiplication  by
#     a complex number L, such that |L|=1.
# 
#   -- ALGLIB --
#      Copyright 2005, 23 March 2007 by Bochkanov Sergey
#

SYNTAX: result, d, z = xalglib.hmatrixevd(a, n, zneeded, isupper)

hmatrixevdi function

#
# Subroutine for finding the eigenvalues and  eigenvectors  of  a  Hermitian
# matrix with given indexes by using bisection and inverse iteration methods
# 
# Input parameters:
#     A       -   Hermitian matrix which is given  by  its  upper  or  lower
#                 triangular part.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     ZNeeded -   flag controlling whether the eigenvectors  are  needed  or
#                 not. If ZNeeded is equal to:
#                  * 0, the eigenvectors are not returned;
#                  * 1, the eigenvectors are returned.
#     IsUpperA -  storage format of matrix A.
#     I1, I2 -    index interval for searching (from I1 to I2).
#                 0 <= I1 <= I2 <= N-1.
# 
# Output parameters:
#     W       -   array of the eigenvalues found.
#                 Array whose index ranges within [0..I2-I1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z hasn't changed;
#                  * 1, Z contains eigenvectors.
#                 Array whose indexes range within [0..N-1, 0..I2-I1].
#                 In  that  case,  the eigenvectors are stored in the matrix
#                 columns.
# 
# Result:
#     True, if successful. W contains the eigenvalues, Z contains the
#     eigenvectors (if needed).
# 
#     False, if the bisection method subroutine  wasn't  able  to  find  the
#     eigenvalues  in  the  given  interval  or  if  the  inverse  iteration
#     subroutine wasn't able to find  all  the  corresponding  eigenvectors.
#     In that case, the eigenvalues and eigenvectors are not returned.
# 
# Note:
#     eigen vectors of Hermitian matrix are defined up to multiplication  by
#     a complex number L, such as |L|=1.
# 
#   -- ALGLIB --
#      Copyright 07.01.2006, 24.03.2007 by Bochkanov Sergey.
#

SYNTAX: result, w, z = xalglib.hmatrixevdi(a, n, zneeded, isupper, i1, i2)

hmatrixevdr function

#
# Subroutine for finding the eigenvalues (and eigenvectors) of  a  Hermitian
# matrix  in  a  given half-interval (A, B] by using a bisection and inverse
# iteration
# 
# Input parameters:
#     A       -   Hermitian matrix which is given  by  its  upper  or  lower
#                 triangular  part.  Array  whose   indexes   range   within
#                 [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     ZNeeded -   flag controlling whether the eigenvectors  are  needed  or
#                 not. If ZNeeded is equal to:
#                  * 0, the eigenvectors are not returned;
#                  * 1, the eigenvectors are returned.
#     IsUpperA -  storage format of matrix A.
#     B1, B2 -    half-interval (B1, B2] to search eigenvalues in.
# 
# Output parameters:
#     M       -   number of eigenvalues found in a given half-interval, M>=0
#     W       -   array of the eigenvalues found.
#                 Array whose index ranges within [0..M-1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z hasn't changed;
#                  * 1, Z contains eigenvectors.
#                 Array whose indexes range within [0..N-1, 0..M-1].
#                 The eigenvectors are stored in the matrix columns.
# 
# Result:
#     True, if successful. M contains the number of eigenvalues in the given
#     half-interval (could be equal to 0), W contains the eigenvalues,
#     Z contains the eigenvectors (if needed).
# 
#     False, if the bisection method subroutine  wasn't  able  to  find  the
#     eigenvalues  in  the  given  interval  or  if  the  inverse  iteration
#     subroutine  wasn't  able  to  find all the corresponding eigenvectors.
#     In that case, the eigenvalues and eigenvectors are not returned, M  is
#     equal to 0.
# 
# Note:
#     eigen vectors of Hermitian matrix are defined up to multiplication  by
#     a complex number L, such as |L|=1.
# 
#   -- ALGLIB --
#      Copyright 07.01.2006, 24.03.2007 by Bochkanov Sergey.
#

SYNTAX: result, m, w, z = xalglib.hmatrixevdr(a, n, zneeded, isupper, b1, b2)

rmatrixevd function

#
# Finding eigenvalues and eigenvectors of a general (unsymmetric) matrix
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes one  important  improvement   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison. Speed-up provided by MKL for this particular problem (EVD)
#   ! is really high, because  MKL  uses combination of (a) better low-level
#   ! optimizations, and (b) better EVD algorithms.
#   !
#   ! On one particular SSE-capable  machine  for  N=1024,  commercial  MKL-
#   ! -capable ALGLIB was:
#   ! * 7-10 times faster than open source "generic C" version
#   ! * 15-18 times faster than "pure C#" version
#   !
#   ! Multithreaded acceleration is NOT supported for this function.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# The algorithm finds eigenvalues and eigenvectors of a general matrix by
# using the QR algorithm with multiple shifts. The algorithm can find
# eigenvalues and both left and right eigenvectors.
# 
# The right eigenvector is a vector x such that A*x = w*x, and the left
# eigenvector is a vector y such that y'*A = w*y' (here y' implies a complex
# conjugate transposition of vector y).
# 
# Input parameters:
#     A       -   matrix. Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     VNeeded -   flag controlling whether eigenvectors are needed or not.
#                 If VNeeded is equal to:
#                  * 0, eigenvectors are not returned;
#                  * 1, right eigenvectors are returned;
#                  * 2, left eigenvectors are returned;
#                  * 3, both left and right eigenvectors are returned.
# 
# Output parameters:
#     WR      -   real parts of eigenvalues.
#                 Array whose index ranges within [0..N-1].
#     WR      -   imaginary parts of eigenvalues.
#                 Array whose index ranges within [0..N-1].
#     VL, VR  -   arrays of left and right eigenvectors (if they are needed).
#                 If WI[i]=0, the respective eigenvalue is a real number,
#                 and it corresponds to the column number I of matrices VL/VR.
#                 If WI[i]>0, we have a pair of complex conjugate numbers with
#                 positive and negative imaginary parts:
#                     the first eigenvalue WR[i] + sqrt(-1)*WI[i];
#                     the second eigenvalue WR[i+1] + sqrt(-1)*WI[i+1];
#                     WI[i]>0
#                     WI[i+1] = -WI[i] < 0
#                 In that case, the eigenvector  corresponding to the first
#                 eigenvalue is located in i and i+1 columns of matrices
#                 VL/VR (the column number i contains the real part, and the
#                 column number i+1 contains the imaginary part), and the vector
#                 corresponding to the second eigenvalue is a complex conjugate to
#                 the first vector.
#                 Arrays whose indexes range within [0..N-1, 0..N-1].
# 
# Result:
#     True, if the algorithm has converged.
#     False, if the algorithm has not converged.
# 
# Note 1:
#     Some users may ask the following question: what if WI[N-1]>0?
#     WI[N] must contain an eigenvalue which is complex conjugate to the
#     N-th eigenvalue, but the array has only size N?
#     The answer is as follows: such a situation cannot occur because the
#     algorithm finds a pairs of eigenvalues, therefore, if WI[i]>0, I is
#     strictly less than N-1.
# 
# Note 2:
#     The algorithm performance depends on the value of the internal parameter
#     NS of the InternalSchurDecomposition subroutine which defines the number
#     of shifts in the QR algorithm (similarly to the block width in block-matrix
#     algorithms of linear algebra). If you require maximum performance
#     on your machine, it is recommended to adjust this parameter manually.
# 
# 
# See also the InternalTREVC subroutine.
# 
# The algorithm is based on the LAPACK 3.0 library.
#

SYNTAX: result, wr, wi, vl, vr = xalglib.rmatrixevd(a, n, vneeded)

smatrixevd function

#
# Finding the eigenvalues and eigenvectors of a symmetric matrix
# 
# The algorithm finds eigen pairs of a symmetric matrix by reducing it to
# tridiagonal form and using the QL/QR algorithm.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes one  important  improvement   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! Multithreaded acceleration is NOT supported for this function.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   symmetric matrix which is given by its upper or lower
#                 triangular part.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     ZNeeded -   flag controlling whether the eigenvectors are needed or not.
#                 If ZNeeded is equal to:
#                  * 0, the eigenvectors are not returned;
#                  * 1, the eigenvectors are returned.
#     IsUpper -   storage format.
# 
# Output parameters:
#     D       -   eigenvalues in ascending order.
#                 Array whose index ranges within [0..N-1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z hasn't changed;
#                  * 1, Z contains the eigenvectors.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#                 The eigenvectors are stored in the matrix columns.
# 
# Result:
#     True, if the algorithm has converged.
#     False, if the algorithm hasn't converged (rare case).
# 
#   -- ALGLIB --
#      Copyright 2005-2008 by Bochkanov Sergey
#

SYNTAX: result, d, z = xalglib.smatrixevd(a, n, zneeded, isupper)

smatrixevdi function

#
# Subroutine for finding the eigenvalues and  eigenvectors  of  a  symmetric
# matrix with given indexes by using bisection and inverse iteration methods.
# 
# Input parameters:
#     A       -   symmetric matrix which is given by its upper or lower
#                 triangular part. Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     ZNeeded -   flag controlling whether the eigenvectors are needed or not.
#                 If ZNeeded is equal to:
#                  * 0, the eigenvectors are not returned;
#                  * 1, the eigenvectors are returned.
#     IsUpperA -  storage format of matrix A.
#     I1, I2 -    index interval for searching (from I1 to I2).
#                 0 <= I1 <= I2 <= N-1.
# 
# Output parameters:
#     W       -   array of the eigenvalues found.
#                 Array whose index ranges within [0..I2-I1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z hasn't changed;
#                  * 1, Z contains eigenvectors.
#                 Array whose indexes range within [0..N-1, 0..I2-I1].
#                 In that case, the eigenvectors are stored in the matrix columns.
# 
# Result:
#     True, if successful. W contains the eigenvalues, Z contains the
#     eigenvectors (if needed).
# 
#     False, if the bisection method subroutine wasn't able to find the
#     eigenvalues in the given interval or if the inverse iteration subroutine
#     wasn't able to find all the corresponding eigenvectors.
#     In that case, the eigenvalues and eigenvectors are not returned.
# 
#   -- ALGLIB --
#      Copyright 07.01.2006 by Bochkanov Sergey
#

SYNTAX: result, w, z = xalglib.smatrixevdi(a, n, zneeded, isupper, i1, i2)

smatrixevdr function

#
# Subroutine for finding the eigenvalues (and eigenvectors) of  a  symmetric
# matrix  in  a  given half open interval (A, B] by using  a  bisection  and
# inverse iteration
# 
# Input parameters:
#     A       -   symmetric matrix which is given by its upper or lower
#                 triangular part. Array [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     ZNeeded -   flag controlling whether the eigenvectors are needed or not.
#                 If ZNeeded is equal to:
#                  * 0, the eigenvectors are not returned;
#                  * 1, the eigenvectors are returned.
#     IsUpperA -  storage format of matrix A.
#     B1, B2 -    half open interval (B1, B2] to search eigenvalues in.
# 
# Output parameters:
#     M       -   number of eigenvalues found in a given half-interval (M>=0).
#     W       -   array of the eigenvalues found.
#                 Array whose index ranges within [0..M-1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z hasn't changed;
#                  * 1, Z contains eigenvectors.
#                 Array whose indexes range within [0..N-1, 0..M-1].
#                 The eigenvectors are stored in the matrix columns.
# 
# Result:
#     True, if successful. M contains the number of eigenvalues in the given
#     half-interval (could be equal to 0), W contains the eigenvalues,
#     Z contains the eigenvectors (if needed).
# 
#     False, if the bisection method subroutine wasn't able to find the
#     eigenvalues in the given interval or if the inverse iteration subroutine
#     wasn't able to find all the corresponding eigenvectors.
#     In that case, the eigenvalues and eigenvectors are not returned,
#     M is equal to 0.
# 
#   -- ALGLIB --
#      Copyright 07.01.2006 by Bochkanov Sergey
#

SYNTAX: result, m, w, z = xalglib.smatrixevdr(a, n, zneeded, isupper, b1, b2)

smatrixtdevd function

#
# Finding the eigenvalues and eigenvectors of a tridiagonal symmetric matrix
# 
# The algorithm finds the eigen pairs of a tridiagonal symmetric matrix by
# using an QL/QR algorithm with implicit shifts.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes one  important  improvement   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! Multithreaded acceleration is NOT supported for this function.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     D       -   the main diagonal of a tridiagonal matrix.
#                 Array whose index ranges within [0..N-1].
#     E       -   the secondary diagonal of a tridiagonal matrix.
#                 Array whose index ranges within [0..N-2].
#     N       -   size of matrix A.
#     ZNeeded -   flag controlling whether the eigenvectors are needed or not.
#                 If ZNeeded is equal to:
#                  * 0, the eigenvectors are not needed;
#                  * 1, the eigenvectors of a tridiagonal matrix
#                    are multiplied by the square matrix Z. It is used if the
#                    tridiagonal matrix is obtained by the similarity
#                    transformation of a symmetric matrix;
#                  * 2, the eigenvectors of a tridiagonal matrix replace the
#                    square matrix Z;
#                  * 3, matrix Z contains the first row of the eigenvectors
#                    matrix.
#     Z       -   if ZNeeded=1, Z contains the square matrix by which the
#                 eigenvectors are multiplied.
#                 Array whose indexes range within [0..N-1, 0..N-1].
# 
# Output parameters:
#     D       -   eigenvalues in ascending order.
#                 Array whose index ranges within [0..N-1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z hasn't changed;
#                  * 1, Z contains the product of a given matrix (from the left)
#                    and the eigenvectors matrix (from the right);
#                  * 2, Z contains the eigenvectors.
#                  * 3, Z contains the first row of the eigenvectors matrix.
#                 If ZNeeded<3, Z is the array whose indexes range within [0..N-1, 0..N-1].
#                 In that case, the eigenvectors are stored in the matrix columns.
#                 If ZNeeded=3, Z is the array whose indexes range within [0..0, 0..N-1].
# 
# Result:
#     True, if the algorithm has converged.
#     False, if the algorithm hasn't converged.
# 
#   -- LAPACK routine (version 3.0) --
#      Univ. of Tennessee, Univ. of California Berkeley, NAG Ltd.,
#      Courant Institute, Argonne National Lab, and Rice University
#      September 30, 1994
#

SYNTAX: result, d, z = xalglib.smatrixtdevd(d, e, n, zneeded, z)

smatrixtdevdi function

#
# Subroutine for finding tridiagonal matrix eigenvalues/vectors with given
# indexes (in ascending order) by using the bisection and inverse iteraion.
# 
# Input parameters:
#     D       -   the main diagonal of a tridiagonal matrix.
#                 Array whose index ranges within [0..N-1].
#     E       -   the secondary diagonal of a tridiagonal matrix.
#                 Array whose index ranges within [0..N-2].
#     N       -   size of matrix. N>=0.
#     ZNeeded -   flag controlling whether the eigenvectors are needed or not.
#                 If ZNeeded is equal to:
#                  * 0, the eigenvectors are not needed;
#                  * 1, the eigenvectors of a tridiagonal matrix are multiplied
#                    by the square matrix Z. It is used if the
#                    tridiagonal matrix is obtained by the similarity transformation
#                    of a symmetric matrix.
#                  * 2, the eigenvectors of a tridiagonal matrix replace
#                    matrix Z.
#     I1, I2  -   index interval for searching (from I1 to I2).
#                 0 <= I1 <= I2 <= N-1.
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z isn't used and remains unchanged;
#                  * 1, Z contains the square matrix (array whose indexes range within [0..N-1, 0..N-1])
#                    which reduces the given symmetric matrix to  tridiagonal form;
#                  * 2, Z isn't used (but changed on the exit).
# 
# Output parameters:
#     D       -   array of the eigenvalues found.
#                 Array whose index ranges within [0..I2-I1].
#     Z       -   if ZNeeded is equal to:
#                  * 0, doesn't contain any information;
#                  * 1, contains the product of a given NxN matrix Z (from the left) and
#                    Nx(I2-I1) matrix of the eigenvectors found (from the right).
#                    Array whose indexes range within [0..N-1, 0..I2-I1].
#                  * 2, contains the matrix of the eigenvalues found.
#                    Array whose indexes range within [0..N-1, 0..I2-I1].
# 
# 
# Result:
# 
#     True, if successful. In that case, D contains the eigenvalues,
#     Z contains the eigenvectors (if needed).
#     It should be noted that the subroutine changes the size of arrays D and Z.
# 
#     False, if the bisection method subroutine wasn't able to find the eigenvalues
#     in the given interval or if the inverse iteration subroutine wasn't able
#     to find all the corresponding eigenvectors. In that case, the eigenvalues
#     and eigenvectors are not returned.
# 
#   -- ALGLIB --
#      Copyright 25.12.2005 by Bochkanov Sergey
#

SYNTAX: result, d, z = xalglib.smatrixtdevdi(d, e, n, zneeded, i1, i2, z)

smatrixtdevdr function

#
# Subroutine for finding the tridiagonal matrix eigenvalues/vectors in a
# given half-interval (A, B] by using bisection and inverse iteration.
# 
# Input parameters:
#     D       -   the main diagonal of a tridiagonal matrix.
#                 Array whose index ranges within [0..N-1].
#     E       -   the secondary diagonal of a tridiagonal matrix.
#                 Array whose index ranges within [0..N-2].
#     N       -   size of matrix, N>=0.
#     ZNeeded -   flag controlling whether the eigenvectors are needed or not.
#                 If ZNeeded is equal to:
#                  * 0, the eigenvectors are not needed;
#                  * 1, the eigenvectors of a tridiagonal matrix are multiplied
#                    by the square matrix Z. It is used if the tridiagonal
#                    matrix is obtained by the similarity transformation
#                    of a symmetric matrix.
#                  * 2, the eigenvectors of a tridiagonal matrix replace matrix Z.
#     A, B    -   half-interval (A, B] to search eigenvalues in.
#     Z       -   if ZNeeded is equal to:
#                  * 0, Z isn't used and remains unchanged;
#                  * 1, Z contains the square matrix (array whose indexes range
#                    within [0..N-1, 0..N-1]) which reduces the given symmetric
#                    matrix to tridiagonal form;
#                  * 2, Z isn't used (but changed on the exit).
# 
# Output parameters:
#     D       -   array of the eigenvalues found.
#                 Array whose index ranges within [0..M-1].
#     M       -   number of eigenvalues found in the given half-interval (M>=0).
#     Z       -   if ZNeeded is equal to:
#                  * 0, doesn't contain any information;
#                  * 1, contains the product of a given NxN matrix Z (from the
#                    left) and NxM matrix of the eigenvectors found (from the
#                    right). Array whose indexes range within [0..N-1, 0..M-1].
#                  * 2, contains the matrix of the eigenvectors found.
#                    Array whose indexes range within [0..N-1, 0..M-1].
# 
# Result:
# 
#     True, if successful. In that case, M contains the number of eigenvalues
#     in the given half-interval (could be equal to 0), D contains the eigenvalues,
#     Z contains the eigenvectors (if needed).
#     It should be noted that the subroutine changes the size of arrays D and Z.
# 
#     False, if the bisection method subroutine wasn't able to find the
#     eigenvalues in the given interval or if the inverse iteration subroutine
#     wasn't able to find all the corresponding eigenvectors. In that case,
#     the eigenvalues and eigenvectors are not returned, M is equal to 0.
# 
#   -- ALGLIB --
#      Copyright 31.03.2008 by Bochkanov Sergey
#

SYNTAX: result, d, m, z = xalglib.smatrixtdevdr(d, e, n, zneeded, a, b, z)

expintegrals module

exponentialintegralei function

#
# Exponential integral Ei(x)
# 
#               x
#                -     t
#               | |   e
#    Ei(x) =   -|-   ---  dt .
#             | |     t
#              -
#             -inf
# 
# Not defined for x <= 0.
# See also expn.c.
# 
# 
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE       0,100       50000      8.6e-16     1.3e-16
# 
# Cephes Math Library Release 2.8:  May, 1999
# Copyright 1999 by Stephen L. Moshier
#

SYNTAX: result = xalglib.exponentialintegralei(x)

exponentialintegralen function

#
# Exponential integral En(x)
# 
# Evaluates the exponential integral
# 
#                 inf.
#                   -
#                  | |   -xt
#                  |    e
#      E (x)  =    |    ----  dt.
#       n          |      n
#                | |     t
#                 -
#                  1
# 
# 
# Both n and x must be nonnegative.
# 
# The routine employs either a power series, a continued
# fraction, or an asymptotic formula depending on the
# relative values of n and x.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0, 30       10000       1.7e-15     3.6e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1985, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.exponentialintegralen(x, n)

fdistr module

fcdistribution function

#
# Complemented F distribution
# 
# Returns the area from x to infinity under the F density
# function (also known as Snedcor's density or the
# variance ratio density).
# 
# 
#                      inf.
#                       -
#              1       | |  a-1      b-1
# 1-P(x)  =  ------    |   t    (1-t)    dt
#            B(a,b)  | |
#                     -
#                      x
# 
# 
# The incomplete beta integral is used, according to the
# formula
# 
# P(x) = incbet( df2/2, df1/2, (df2/(df2 + df1*x) ).
# 
# 
# ACCURACY:
# 
# Tested at random points (a,b,x) in the indicated intervals.
#                x     a,b                     Relative error:
# arithmetic  domain  domain     # trials      peak         rms
#    IEEE      0,1    1,100       100000      3.7e-14     5.9e-16
#    IEEE      1,5    1,100       100000      8.0e-15     1.6e-15
#    IEEE      0,1    1,10000     100000      1.8e-11     3.5e-13
#    IEEE      1,5    1,10000     100000      2.0e-11     3.0e-12
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.fcdistribution(a, b, x)

fdistribution function

#
# F distribution
# 
# Returns the area from zero to x under the F density
# function (also known as Snedcor's density or the
# variance ratio density).  This is the density
# of x = (u1/df1)/(u2/df2), where u1 and u2 are random
# variables having Chi square distributions with df1
# and df2 degrees of freedom, respectively.
# The incomplete beta integral is used, according to the
# formula
# 
# P(x) = incbet( df1/2, df2/2, (df1*x/(df2 + df1*x) ).
# 
# 
# The arguments a and b are greater than zero, and x is
# nonnegative.
# 
# ACCURACY:
# 
# Tested at random points (a,b,x).
# 
#                x     a,b                     Relative error:
# arithmetic  domain  domain     # trials      peak         rms
#    IEEE      0,1    0,100       100000      9.8e-15     1.7e-15
#    IEEE      1,5    0,100       100000      6.5e-15     3.5e-16
#    IEEE      0,1    1,10000     100000      2.2e-11     3.3e-12
#    IEEE      1,5    1,10000     100000      1.1e-11     1.7e-13
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.fdistribution(a, b, x)

invfdistribution function

#
# Inverse of complemented F distribution
# 
# Finds the F density argument x such that the integral
# from x to infinity of the F density is equal to the
# given probability p.
# 
# This is accomplished using the inverse beta integral
# function and the relations
# 
#      z = incbi( df2/2, df1/2, p )
#      x = df2 (1-z) / (df1 z).
# 
# Note: the following relations hold for the inverse of
# the uncomplemented F distribution:
# 
#      z = incbi( df1/2, df2/2, p )
#      x = df2 z / (df1 (1-z)).
# 
# ACCURACY:
# 
# Tested at random points (a,b,p).
# 
#              a,b                     Relative error:
# arithmetic  domain     # trials      peak         rms
#  For p between .001 and 1:
#    IEEE     1,100       100000      8.3e-15     4.7e-16
#    IEEE     1,10000     100000      2.1e-11     1.4e-13
#  For p between 10^-6 and 10^-3:
#    IEEE     1,100        50000      1.3e-12     8.4e-15
#    IEEE     1,10000      50000      3.0e-12     4.8e-14
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.invfdistribution(a, b, y)

fft module

fftc1d function

#
# 1-dimensional complex FFT.
# 
# Array size N may be arbitrary number (composite or prime).  Composite  N's
# are handled with cache-oblivious variation of  a  Cooley-Tukey  algorithm.
# Small prime-factors are transformed using hard coded  codelets (similar to
# FFTW codelets, but without low-level  optimization),  large  prime-factors
# are handled with Bluestein's algorithm.
# 
# Fastests transforms are for smooth N's (prime factors are 2, 3,  5  only),
# most fast for powers of 2. When N have prime factors  larger  than  these,
# but orders of magnitude smaller than N, computations will be about 4 times
# slower than for nearby highly composite N's. When N itself is prime, speed
# will be 6 times lower.
# 
# Algorithm has O(N*logN) complexity for any N (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..N-1] - complex function to be transformed
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     A   -   DFT of a input array, array[0..N-1]
#             A_out[j] = SUM(A_in[k]*exp(-2*pi*sqrt(-1)*j*k/N), k = 0..N-1)
# 
# 
#   -- ALGLIB --
#      Copyright 29.05.2009 by Bochkanov Sergey
#

SYNTAX: a = xalglib.fftc1d(a, n)
SYNTAX: a = xalglib.fftc1d(a)

Examples:   [1]  [2]  

fftc1dinv function

#
# 1-dimensional complex inverse FFT.
# 
# Array size N may be arbitrary number (composite or prime).  Algorithm  has
# O(N*logN) complexity for any N (composite or prime).
# 
# See FFTC1D() description for more information about algorithm performance.
# 
# INPUT PARAMETERS
#     A   -   array[0..N-1] - complex array to be transformed
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     A   -   inverse DFT of a input array, array[0..N-1]
#             A_out[j] = SUM(A_in[k]/N*exp(+2*pi*sqrt(-1)*j*k/N), k = 0..N-1)
# 
# 
#   -- ALGLIB --
#      Copyright 29.05.2009 by Bochkanov Sergey
#

SYNTAX: a = xalglib.fftc1dinv(a, n)
SYNTAX: a = xalglib.fftc1dinv(a)

Examples:   [1]  [2]  

fftr1d function

#
# 1-dimensional real FFT.
# 
# Algorithm has O(N*logN) complexity for any N (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..N-1] - real function to be transformed
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     F   -   DFT of a input array, array[0..N-1]
#             F[j] = SUM(A[k]*exp(-2*pi*sqrt(-1)*j*k/N), k = 0..N-1)
# 
# NOTE:
#     F[] satisfies symmetry property F[k] = conj(F[N-k]),  so just one half
# of  array  is  usually needed. But for convinience subroutine returns full
# complex array (with frequencies above N/2), so its result may be  used  by
# other FFT-related subroutines.
# 
# 
#   -- ALGLIB --
#      Copyright 01.06.2009 by Bochkanov Sergey
#

SYNTAX: f = xalglib.fftr1d(a, n)
SYNTAX: f = xalglib.fftr1d(a)

Examples:   [1]  [2]  

fftr1dinv function

#
# 1-dimensional real inverse FFT.
# 
# Algorithm has O(N*logN) complexity for any N (composite or prime).
# 
# INPUT PARAMETERS
#     F   -   array[0..floor(N/2)] - frequencies from forward real FFT
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     A   -   inverse DFT of a input array, array[0..N-1]
# 
# NOTE:
#     F[] should satisfy symmetry property F[k] = conj(F[N-k]), so just  one
# half of frequencies array is needed - elements from 0 to floor(N/2).  F[0]
# is ALWAYS real. If N is even F[floor(N/2)] is real too. If N is odd,  then
# F[floor(N/2)] has no special properties.
# 
# Relying on properties noted above, FFTR1DInv subroutine uses only elements
# from 0th to floor(N/2)-th. It ignores imaginary part of F[0],  and in case
# N is even it ignores imaginary part of F[floor(N/2)] too.
# 
# When you call this function using full arguments list - "FFTR1DInv(F,N,A)"
# - you can pass either either frequencies array with N elements or  reduced
# array with roughly N/2 elements - subroutine will  successfully  transform
# both.
# 
# If you call this function using reduced arguments list -  "FFTR1DInv(F,A)"
# - you must pass FULL array with N elements (although higher  N/2 are still
# not used) because array size is used to automatically determine FFT length
# 
# 
#   -- ALGLIB --
#      Copyright 01.06.2009 by Bochkanov Sergey
#

SYNTAX: a = xalglib.fftr1dinv(f, n)
SYNTAX: a = xalglib.fftr1dinv(f)

Examples:   [1]  [2]  

fft_complex_d1 example

import xalglib



#
# first we demonstrate forward FFT:
# [1i,1i,1i,1i] is converted to [4i, 0, 0, 0]
#
z = [1j,1j,1j,1j]
z = xalglib.fftc1d(z)
print(z) # expected [4j,0,0,0]

#
# now we convert [4i, 0, 0, 0] back to [1i,1i,1i,1i]
# with backward FFT
#
z = xalglib.fftc1dinv(z)
print(z) # expected [1j,1j,1j,1j]

fft_complex_d2 example

import xalglib



#
# first we demonstrate forward FFT:
# [0,1,0,1i] is converted to [1+1i, -1-1i, -1-1i, 1+1i]
#
z = [0,1,0,1j]
z = xalglib.fftc1d(z)
print(z) # expected [1+1j, -1-1j, -1-1j, 1+1j]

#
# now we convert result back with backward FFT
#
z = xalglib.fftc1dinv(z)
print(z) # expected [0,1,0,1j]

fft_real_d1 example

import xalglib



#
# first we demonstrate forward FFT:
# [1,1,1,1] is converted to [4, 0, 0, 0]
#
x = [1,1,1,1]
f = xalglib.fftr1d(x)
print(f) # expected [4,0,0,0]

#
# now we convert [4, 0, 0, 0] back to [1,1,1,1]
# with backward FFT
#
x2 = xalglib.fftr1dinv(f)
print(x2) # expected [1,1,1,1]

fft_real_d2 example

import xalglib



#
# first we demonstrate forward FFT:
# [1,2,3,4] is converted to [10, -2+2i, -2, -2-2i]
#
# note that output array is self-adjoint:
# * f[0] = conj(f[0])
# * f[1] = conj(f[3])
# * f[2] = conj(f[2])
#
x = [1,2,3,4]
f = xalglib.fftr1d(x)
print(f) # expected [10, -2+2j, -2, -2-2j]

#
# now we convert [10, -2+2i, -2, -2-2i] back to [1,2,3,4]
#
x2 = xalglib.fftr1dinv(f)
print(x2) # expected [1,2,3,4]

#
# remember that F is self-adjoint? It means that we can pass just half
# (slightly larger than half) of F to inverse real FFT and still get our result.
#
# I.e. instead [10, -2+2i, -2, -2-2i] we pass just [10, -2+2i, -2] and everything works!
#
# NOTE: in this case we should explicitly pass array length (which is 4) to ALGLIB;
# if not, it will automatically use array length to determine FFT size and
# will erroneously make half-length FFT.
#
f = [10, -2+2j, -2]
x2 = xalglib.fftr1dinv(f, 4)
print(x2) # expected [1,2,3,4]

fht module

fhtr1d function

#
# 1-dimensional Fast Hartley Transform.
# 
# Algorithm has O(N*logN) complexity for any N (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..N-1] - real function to be transformed
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     A   -   FHT of a input array, array[0..N-1],
#             A_out[k] = sum(A_in[j]*(cos(2*pi*j*k/N)+sin(2*pi*j*k/N)), j=0..N-1)
# 
# 
#   -- ALGLIB --
#      Copyright 04.06.2009 by Bochkanov Sergey
#

SYNTAX: a = xalglib.fhtr1d(a, n)

fhtr1dinv function

#
# 1-dimensional inverse FHT.
# 
# Algorithm has O(N*logN) complexity for any N (composite or prime).
# 
# INPUT PARAMETERS
#     A   -   array[0..N-1] - complex array to be transformed
#     N   -   problem size
# 
# OUTPUT PARAMETERS
#     A   -   inverse FHT of a input array, array[0..N-1]
# 
# 
#   -- ALGLIB --
#      Copyright 29.05.2009 by Bochkanov Sergey
#

SYNTAX: a = xalglib.fhtr1dinv(a, n)

filters module

filterema function

#
# Filters: exponential moving averages.
# 
# This filter replaces array by results of EMA(alpha) filter. EMA(alpha) is
# defined as filter which replaces X[] by S[]:
#     S[0] = X[0]
#     S[t] = alpha*X[t] + (1-alpha)*S[t-1]
# 
# INPUT PARAMETERS:
#     X           -   array[N], array to process. It can be larger than N,
#                     in this case only first N points are processed.
#     N           -   points count, N>=0
#     alpha       -   0<alpha<=1, smoothing parameter.
# 
# OUTPUT PARAMETERS:
#     X           -   array, whose first N elements were processed
#                     with EMA(alpha)
# 
# NOTE 1: this function uses efficient in-place  algorithm  which  does not
#         allocate temporary arrays.
# 
# NOTE 2: this algorithm uses BOTH previous points and  current  one,  i.e.
#         new value of X[i] depends on BOTH previous point and X[i] itself.
# 
# NOTE 3: technical analytis users quite often work  with  EMA  coefficient
#         expressed in DAYS instead of fractions. If you want to  calculate
#         EMA(N), where N is a number of days, you can use alpha=2/(N+1).
# 
#   -- ALGLIB --
#      Copyright 25.10.2011 by Bochkanov Sergey
#

SYNTAX: x = xalglib.filterema(x, n, alpha)
SYNTAX: x = xalglib.filterema(x, alpha)

Examples:   [1]  

filterlrma function

#
# Filters: linear regression moving averages.
# 
# This filter replaces array by results of LRMA(K) filter.
# 
# LRMA(K) is defined as filter which, for each data  point,  builds  linear
# regression  model  using  K  prevous  points (point itself is included in
# these K points) and calculates value of this linear model at the point in
# question.
# 
# INPUT PARAMETERS:
#     X           -   array[N], array to process. It can be larger than N,
#                     in this case only first N points are processed.
#     N           -   points count, N>=0
#     K           -   K>=1 (K can be larger than N ,  such  cases  will  be
#                     correctly handled). Window width. K=1 corresponds  to
#                     identity transformation (nothing changes).
# 
# OUTPUT PARAMETERS:
#     X           -   array, whose first N elements were processed with SMA(K)
# 
# NOTE 1: this function uses efficient in-place  algorithm  which  does not
#         allocate temporary arrays.
# 
# NOTE 2: this algorithm makes only one pass through array and uses running
#         sum  to speed-up calculation of the averages. Additional measures
#         are taken to ensure that running sum on a long sequence  of  zero
#         elements will be correctly reset to zero even in the presence  of
#         round-off error.
# 
# NOTE 3: this  is  unsymmetric version of the algorithm,  which  does  NOT
#         averages points after the current one. Only X[i], X[i-1], ... are
#         used when calculating new value of X[i]. We should also note that
#         this algorithm uses BOTH previous points and  current  one,  i.e.
#         new value of X[i] depends on BOTH previous point and X[i] itself.
# 
#   -- ALGLIB --
#      Copyright 25.10.2011 by Bochkanov Sergey
#

SYNTAX: x = xalglib.filterlrma(x, n, k)
SYNTAX: x = xalglib.filterlrma(x, k)

Examples:   [1]  

filtersma function

#
# Filters: simple moving averages (unsymmetric).
# 
# This filter replaces array by results of SMA(K) filter. SMA(K) is defined
# as filter which averages at most K previous points (previous - not points
# AROUND central point) - or less, in case of the first K-1 points.
# 
# INPUT PARAMETERS:
#     X           -   array[N], array to process. It can be larger than N,
#                     in this case only first N points are processed.
#     N           -   points count, N>=0
#     K           -   K>=1 (K can be larger than N ,  such  cases  will  be
#                     correctly handled). Window width. K=1 corresponds  to
#                     identity transformation (nothing changes).
# 
# OUTPUT PARAMETERS:
#     X           -   array, whose first N elements were processed with SMA(K)
# 
# NOTE 1: this function uses efficient in-place  algorithm  which  does not
#         allocate temporary arrays.
# 
# NOTE 2: this algorithm makes only one pass through array and uses running
#         sum  to speed-up calculation of the averages. Additional measures
#         are taken to ensure that running sum on a long sequence  of  zero
#         elements will be correctly reset to zero even in the presence  of
#         round-off error.
# 
# NOTE 3: this  is  unsymmetric version of the algorithm,  which  does  NOT
#         averages points after the current one. Only X[i], X[i-1], ... are
#         used when calculating new value of X[i]. We should also note that
#         this algorithm uses BOTH previous points and  current  one,  i.e.
#         new value of X[i] depends on BOTH previous point and X[i] itself.
# 
#   -- ALGLIB --
#      Copyright 25.10.2011 by Bochkanov Sergey
#

SYNTAX: x = xalglib.filtersma(x, n, k)
SYNTAX: x = xalglib.filtersma(x, k)

Examples:   [1]  

filters_d_ema example

import xalglib



#
# Here we demonstrate EMA(0.5) filtering for time series.
#
x = [5,6,7,8]

#
# Apply filter.
# We should get [5, 5.5, 6.25, 7.125] as result
#
x = xalglib.filterema(x, 0.5)
print(x) # expected [5,5.5,6.25,7.125]

filters_d_lrma example

import xalglib



#
# Here we demonstrate LRMA(3) filtering for time series.
#
x = [7,8,8,9,12,12]

#
# Apply filter.
# We should get [7.0000, 8.0000, 8.1667, 8.8333, 11.6667, 12.5000] as result
#    
x = xalglib.filterlrma(x, 3)
print(x) # expected [7.0000,8.0000,8.1667,8.8333,11.6667,12.5000]

filters_d_sma example

import xalglib



#
# Here we demonstrate SMA(k) filtering for time series.
#
x = [5,6,7,8]

#
# Apply filter.
# We should get [5, 5.5, 6.5, 7.5] as result
#
x = xalglib.filtersma(x, 2)
print(x) # expected [5,5.5,6.5,7.5]

fresnel module

fresnelintegral function

#
# Fresnel integral
# 
# Evaluates the Fresnel integrals
# 
#           x
#           -
#          | |
# C(x) =   |   cos(pi/2 t**2) dt,
#        | |
#         -
#          0
# 
#           x
#           -
#          | |
# S(x) =   |   sin(pi/2 t**2) dt.
#        | |
#         -
#          0
# 
# 
# The integrals are evaluated by a power series for x < 1.
# For x >= 1 auxiliary functions f(x) and g(x) are employed
# such that
# 
# C(x) = 0.5 + f(x) sin( pi/2 x**2 ) - g(x) cos( pi/2 x**2 )
# S(x) = 0.5 - f(x) cos( pi/2 x**2 ) - g(x) sin( pi/2 x**2 )
# 
# 
# 
# ACCURACY:
# 
#  Relative error.
# 
# Arithmetic  function   domain     # trials      peak         rms
#   IEEE       S(x)      0, 10       10000       2.0e-15     3.2e-16
#   IEEE       C(x)      0, 10       10000       1.8e-15     3.3e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier
#

SYNTAX: c, s = xalglib.fresnelintegral(x, c, s)

gammafunc module

gammafunction function

#
# Gamma function
# 
# Input parameters:
#     X   -   argument
# 
# Domain:
#     0 < X < 171.6
#     -170 < X < 0, X is not an integer.
# 
# Relative error:
#  arithmetic   domain     # trials      peak         rms
#     IEEE    -170,-33      20000       2.3e-15     3.3e-16
#     IEEE     -33,  33     20000       9.4e-16     2.2e-16
#     IEEE      33, 171.6   20000       2.3e-15     3.2e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Original copyright 1984, 1987, 1989, 1992, 2000 by Stephen L. Moshier
# Translated to AlgoPascal by Bochkanov Sergey (2005, 2006, 2007).
#

SYNTAX: result = xalglib.gammafunction(x)

lngamma function

#
# Natural logarithm of gamma function
# 
# Input parameters:
#     X       -   argument
# 
# Result:
#     logarithm of the absolute value of the Gamma(X).
# 
# Output parameters:
#     SgnGam  -   sign(Gamma(X))
# 
# Domain:
#     0 < X < 2.55e305
#     -2.55e305 < X < 0, X is not an integer.
# 
# ACCURACY:
# arithmetic      domain        # trials     peak         rms
#    IEEE    0, 3                 28000     5.4e-16     1.1e-16
#    IEEE    2.718, 2.556e305     40000     3.5e-16     8.3e-17
# The error criterion was relative when the function magnitude
# was greater than one but absolute when it was less than one.
# 
# The following test used the relative error criterion, though
# at certain points the relative error could be much higher than
# indicated.
#    IEEE    -200, -4             10000     4.8e-16     1.3e-16
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1989, 1992, 2000 by Stephen L. Moshier
# Translated to AlgoPascal by Bochkanov Sergey (2005, 2006, 2007).
#

SYNTAX: result, sgngam = xalglib.lngamma(x)

gkq module

gkqgenerategaussjacobi function

#
# Returns   Gauss   and   Gauss-Kronrod   nodes/weights   for   Gauss-Jacobi
# quadrature on [-1,1] with weight function
# 
#     W(x)=Power(1-x,Alpha)*Power(1+x,Beta).
# 
# INPUT PARAMETERS:
#     N           -   number of Kronrod nodes, must be odd number, >=3.
#     Alpha       -   power-law coefficient, Alpha>-1
#     Beta        -   power-law coefficient, Beta>-1
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -5    no real and positive Gauss-Kronrod formula can
#                             be created for such a weight function  with  a
#                             given number of nodes.
#                     * -4    an  error  was   detected   when   calculating
#                             weights/nodes. Alpha or  Beta  are  too  close
#                             to -1 to obtain weights/nodes with high enough
#                             accuracy, or, may be, N is too large.  Try  to
#                             use multiple precision version.
#                     * -3    internal eigenproblem solver hasn't converged
#                     * -1    incorrect N was passed
#                     * +1    OK
#                     * +2    OK, but quadrature rule have exterior  nodes,
#                             x[0]<-1 or x[n-1]>+1
#     X           -   array[0..N-1] - array of quadrature nodes, ordered in
#                     ascending order.
#     WKronrod    -   array[0..N-1] - Kronrod weights
#     WGauss      -   array[0..N-1] - Gauss weights (interleaved with zeros
#                     corresponding to extended Kronrod nodes).
# 
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, wkronrod, wgauss = xalglib.gkqgenerategaussjacobi(n, alpha, beta)

gkqgenerategausslegendre function

#
# Returns   Gauss   and   Gauss-Kronrod   nodes/weights  for  Gauss-Legendre
# quadrature with N points.
# 
# GKQLegendreCalc (calculation) or  GKQLegendreTbl  (precomputed  table)  is
# used depending on machine precision and number of nodes.
# 
# INPUT PARAMETERS:
#     N           -   number of Kronrod nodes, must be odd number, >=3.
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -4    an  error   was   detected   when  calculating
#                             weights/nodes.  N  is  too  large   to  obtain
#                             weights/nodes  with  high   enough   accuracy.
#                             Try  to   use   multiple   precision  version.
#                     * -3    internal eigenproblem solver hasn't converged
#                     * -1    incorrect N was passed
#                     * +1    OK
#     X           -   array[0..N-1] - array of quadrature nodes, ordered in
#                     ascending order.
#     WKronrod    -   array[0..N-1] - Kronrod weights
#     WGauss      -   array[0..N-1] - Gauss weights (interleaved with zeros
#                     corresponding to extended Kronrod nodes).
# 
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, wkronrod, wgauss = xalglib.gkqgenerategausslegendre(n)

gkqgeneraterec function

#
# Computation of nodes and weights of a Gauss-Kronrod quadrature formula
# 
# The algorithm generates the N-point Gauss-Kronrod quadrature formula  with
# weight  function  given  by  coefficients  alpha  and beta of a recurrence
# relation which generates a system of orthogonal polynomials:
# 
#     P-1(x)   =  0
#     P0(x)    =  1
#     Pn+1(x)  =  (x-alpha(n))*Pn(x)  -  beta(n)*Pn-1(x)
# 
# and zero moment Mu0
# 
#     Mu0 = integral(W(x)dx,a,b)
# 
# 
# INPUT PARAMETERS:
#     Alpha       -   alpha coefficients, array[0..floor(3*K/2)].
#     Beta        -   beta coefficients,  array[0..ceil(3*K/2)].
#                     Beta[0] is not used and may be arbitrary.
#                     Beta[I]>0.
#     Mu0         -   zeroth moment of the weight function.
#     N           -   number of nodes of the Gauss-Kronrod quadrature formula,
#                     N >= 3,
#                     N =  2*K+1.
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -5    no real and positive Gauss-Kronrod formula can
#                             be created for such a weight function  with  a
#                             given number of nodes.
#                     * -4    N is too large, task may be ill  conditioned -
#                             x[i]=x[i+1] found.
#                     * -3    internal eigenproblem solver hasn't converged
#                     * -2    Beta[i]<=0
#                     * -1    incorrect N was passed
#                     * +1    OK
#     X           -   array[0..N-1] - array of quadrature nodes,
#                     in ascending order.
#     WKronrod    -   array[0..N-1] - Kronrod weights
#     WGauss      -   array[0..N-1] - Gauss weights (interleaved with zeros
#                     corresponding to extended Kronrod nodes).
# 
#   -- ALGLIB --
#      Copyright 08.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, wkronrod, wgauss = xalglib.gkqgeneraterec(alpha, beta, mu0, n)

gkqlegendrecalc function

#
# Returns Gauss and Gauss-Kronrod nodes for quadrature with N points.
# 
# Reduction to tridiagonal eigenproblem is used.
# 
# INPUT PARAMETERS:
#     N           -   number of Kronrod nodes, must be odd number, >=3.
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -4    an  error   was   detected   when  calculating
#                             weights/nodes.  N  is  too  large   to  obtain
#                             weights/nodes  with  high   enough   accuracy.
#                             Try  to   use   multiple   precision  version.
#                     * -3    internal eigenproblem solver hasn't converged
#                     * -1    incorrect N was passed
#                     * +1    OK
#     X           -   array[0..N-1] - array of quadrature nodes, ordered in
#                     ascending order.
#     WKronrod    -   array[0..N-1] - Kronrod weights
#     WGauss      -   array[0..N-1] - Gauss weights (interleaved with zeros
#                     corresponding to extended Kronrod nodes).
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, wkronrod, wgauss = xalglib.gkqlegendrecalc(n)

gkqlegendretbl function

#
# Returns Gauss and Gauss-Kronrod nodes for quadrature with N  points  using
# pre-calculated table. Nodes/weights were  computed  with  accuracy  up  to
# 1.0E-32 (if MPFR version of ALGLIB is used). In standard double  precision
# accuracy reduces to something about 2.0E-16 (depending  on your compiler's
# handling of long floating point constants).
# 
# INPUT PARAMETERS:
#     N           -   number of Kronrod nodes.
#                     N can be 15, 21, 31, 41, 51, 61.
# 
# OUTPUT PARAMETERS:
#     X           -   array[0..N-1] - array of quadrature nodes, ordered in
#                     ascending order.
#     WKronrod    -   array[0..N-1] - Kronrod weights
#     WGauss      -   array[0..N-1] - Gauss weights (interleaved with zeros
#                     corresponding to extended Kronrod nodes).
# 
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: x, wkronrod, wgauss, eps = xalglib.gkqlegendretbl(n)

gq module

gqgenerategausshermite function

#
# Returns  nodes/weights  for  Gauss-Hermite  quadrature on (-inf,+inf) with
# weight function W(x)=Exp(-x*x)
# 
# INPUT PARAMETERS:
#     N           -   number of nodes, >=1
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -4    an  error  was   detected   when   calculating
#                             weights/nodes.  May be, N is too large. Try to
#                             use multiple precision version.
#                     * -3    internal eigenproblem solver hasn't converged
#                     * -1    incorrect N/Alpha was passed
#                     * +1    OK
#     X           -   array[0..N-1] - array of quadrature nodes,
#                     in ascending order.
#     W           -   array[0..N-1] - array of quadrature weights.
# 
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, w = xalglib.gqgenerategausshermite(n)

gqgenerategaussjacobi function

#
# Returns  nodes/weights  for  Gauss-Jacobi quadrature on [-1,1] with weight
# function W(x)=Power(1-x,Alpha)*Power(1+x,Beta).
# 
# INPUT PARAMETERS:
#     N           -   number of nodes, >=1
#     Alpha       -   power-law coefficient, Alpha>-1
#     Beta        -   power-law coefficient, Beta>-1
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -4    an  error  was   detected   when   calculating
#                             weights/nodes. Alpha or  Beta  are  too  close
#                             to -1 to obtain weights/nodes with high enough
#                             accuracy, or, may be, N is too large.  Try  to
#                             use multiple precision version.
#                     * -3    internal eigenproblem solver hasn't converged
#                     * -1    incorrect N/Alpha/Beta was passed
#                     * +1    OK
#     X           -   array[0..N-1] - array of quadrature nodes,
#                     in ascending order.
#     W           -   array[0..N-1] - array of quadrature weights.
# 
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, w = xalglib.gqgenerategaussjacobi(n, alpha, beta)

gqgenerategausslaguerre function

#
# Returns  nodes/weights  for  Gauss-Laguerre  quadrature  on  [0,+inf) with
# weight function W(x)=Power(x,Alpha)*Exp(-x)
# 
# INPUT PARAMETERS:
#     N           -   number of nodes, >=1
#     Alpha       -   power-law coefficient, Alpha>-1
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -4    an  error  was   detected   when   calculating
#                             weights/nodes. Alpha is too  close  to  -1  to
#                             obtain weights/nodes with high enough accuracy
#                             or, may  be,  N  is  too  large.  Try  to  use
#                             multiple precision version.
#                     * -3    internal eigenproblem solver hasn't converged
#                     * -1    incorrect N/Alpha was passed
#                     * +1    OK
#     X           -   array[0..N-1] - array of quadrature nodes,
#                     in ascending order.
#     W           -   array[0..N-1] - array of quadrature weights.
# 
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, w = xalglib.gqgenerategausslaguerre(n, alpha)

gqgenerategausslegendre function

#
# Returns nodes/weights for Gauss-Legendre quadrature on [-1,1] with N
# nodes.
# 
# INPUT PARAMETERS:
#     N           -   number of nodes, >=1
# 
# OUTPUT PARAMETERS:
#     Info        -   error code:
#                     * -4    an  error   was   detected   when  calculating
#                             weights/nodes.  N  is  too  large   to  obtain
#                             weights/nodes  with  high   enough   accuracy.
#                             Try  to   use   multiple   precision  version.
#                     * -3    internal eigenproblem solver hasn't  converged
#                     * -1    incorrect N was passed
#                     * +1    OK
#     X           -   array[0..N-1] - array of quadrature nodes,
#                     in ascending order.
#     W           -   array[0..N-1] - array of quadrature weights.
# 
# 
#   -- ALGLIB --
#      Copyright 12.05.2009 by Bochkanov Sergey
#

SYNTAX: info, x, w = xalglib.gqgenerategausslegendre(n)

gqgenerategausslobattorec function

#
# Computation of nodes and weights for a Gauss-Lobatto quadrature formula
# 
# The algorithm generates the N-point Gauss-Lobatto quadrature formula  with
# weight function given by coefficients alpha and beta of a recurrence which
# generates a system of orthogonal polynomials.
# 
# P-1(x)   =  0
# P0(x)    =  1
# Pn+1(x)  =  (x-alpha(n))*Pn(x)  -  beta(n)*Pn-1(x)
# 
# and zeroth moment Mu0
# 
# Mu0 = integral(W(x)dx,a,b)
# 
# INPUT PARAMETERS:
#     Alpha   -   array[0..N-2], alpha coefficients
#     Beta    -   array[0..N-2], beta coefficients.
#                 Zero-indexed element is not used, may be arbitrary.
#                 Beta[I]>0
#     Mu0     -   zeroth moment of the weighting function.
#     A       -   left boundary of the integration interval.
#     B       -   right boundary of the integration interval.
#     N       -   number of nodes of the quadrature formula, N>=3
#                 (including the left and right boundary nodes).
# 
# OUTPUT PARAMETERS:
#     Info    -   error code:
#                 * -3    internal eigenproblem solver hasn't converged
#                 * -2    Beta[i]<=0
#                 * -1    incorrect N was passed
#                 *  1    OK
#     X       -   array[0..N-1] - array of quadrature nodes,
#                 in ascending order.
#     W       -   array[0..N-1] - array of quadrature weights.
# 
#   -- ALGLIB --
#      Copyright 2005-2009 by Bochkanov Sergey
#

SYNTAX: info, x, w = xalglib.gqgenerategausslobattorec(alpha, beta, mu0, a, b, n)

gqgenerategaussradaurec function

#
# Computation of nodes and weights for a Gauss-Radau quadrature formula
# 
# The algorithm generates the N-point Gauss-Radau  quadrature  formula  with
# weight function given by the coefficients alpha and  beta  of a recurrence
# which generates a system of orthogonal polynomials.
# 
# P-1(x)   =  0
# P0(x)    =  1
# Pn+1(x)  =  (x-alpha(n))*Pn(x)  -  beta(n)*Pn-1(x)
# 
# and zeroth moment Mu0
# 
# Mu0 = integral(W(x)dx,a,b)
# 
# INPUT PARAMETERS:
#     Alpha   -   array[0..N-2], alpha coefficients.
#     Beta    -   array[0..N-1], beta coefficients
#                 Zero-indexed element is not used.
#                 Beta[I]>0
#     Mu0     -   zeroth moment of the weighting function.
#     A       -   left boundary of the integration interval.
#     N       -   number of nodes of the quadrature formula, N>=2
#                 (including the left boundary node).
# 
# OUTPUT PARAMETERS:
#     Info    -   error code:
#                 * -3    internal eigenproblem solver hasn't converged
#                 * -2    Beta[i]<=0
#                 * -1    incorrect N was passed
#                 *  1    OK
#     X       -   array[0..N-1] - array of quadrature nodes,
#                 in ascending order.
#     W       -   array[0..N-1] - array of quadrature weights.
# 
# 
#   -- ALGLIB --
#      Copyright 2005-2009 by Bochkanov Sergey
#

SYNTAX: info, x, w = xalglib.gqgenerategaussradaurec(alpha, beta, mu0, a, n)

gqgeneraterec function

#
# Computation of nodes and weights for a Gauss quadrature formula
# 
# The algorithm generates the N-point Gauss quadrature formula  with  weight
# function given by coefficients alpha and beta  of  a  recurrence  relation
# which generates a system of orthogonal polynomials:
# 
# P-1(x)   =  0
# P0(x)    =  1
# Pn+1(x)  =  (x-alpha(n))*Pn(x)  -  beta(n)*Pn-1(x)
# 
# and zeroth moment Mu0
# 
# Mu0 = integral(W(x)dx,a,b)
# 
# INPUT PARAMETERS:
#     Alpha   -   array[0..N-1], alpha coefficients
#     Beta    -   array[0..N-1], beta coefficients
#                 Zero-indexed element is not used and may be arbitrary.
#                 Beta[I]>0.
#     Mu0     -   zeroth moment of the weight function.
#     N       -   number of nodes of the quadrature formula, N>=1
# 
# OUTPUT PARAMETERS:
#     Info    -   error code:
#                 * -3    internal eigenproblem solver hasn't converged
#                 * -2    Beta[i]<=0
#                 * -1    incorrect N was passed
#                 *  1    OK
#     X       -   array[0..N-1] - array of quadrature nodes,
#                 in ascending order.
#     W       -   array[0..N-1] - array of quadrature weights.
# 
#   -- ALGLIB --
#      Copyright 2005-2009 by Bochkanov Sergey
#

SYNTAX: info, x, w = xalglib.gqgeneraterec(alpha, beta, mu0, n)

hermite module

hermitecalculate function

#
# Calculation of the value of the Hermite polynomial.
# 
# Parameters:
#     n   -   degree, n>=0
#     x   -   argument
# 
# Result:
#     the value of the Hermite polynomial Hn at x
#

SYNTAX: result = xalglib.hermitecalculate(n, x)

hermitecoefficients function

#
# Representation of Hn as C[0] + C[1]*X + ... + C[N]*X^N
# 
# Input parameters:
#     N   -   polynomial degree, n>=0
# 
# Output parameters:
#     C   -   coefficients
#

SYNTAX: c = xalglib.hermitecoefficients(n)

hermitesum function

#
# Summation of Hermite polynomials using Clenshaw's recurrence formula.
# 
# This routine calculates
#     c[0]*H0(x) + c[1]*H1(x) + ... + c[N]*HN(x)
# 
# Parameters:
#     n   -   degree, n>=0
#     x   -   argument
# 
# Result:
#     the value of the Hermite polynomial at x
#

SYNTAX: result = xalglib.hermitesum(c, n, x)

hqrnd module

hqrndstate class

#
# Portable high quality random number generator state.
# Initialized with HQRNDRandomize() or HQRNDSeed().
# 
# Fields:
#     S1, S2      -   seed values
#     V           -   precomputed value
#     MagicV      -   'magic' value used to determine whether State structure
#                     was correctly initialized.
#

class hqrndstate(object):
    ...

hqrndcontinuous function

#
# This function generates random number from continuous  distribution  given
# by finite sample X.
# 
# INPUT PARAMETERS
#     State   -   high quality random number generator, must be
#                 initialized with HQRNDRandomize() or HQRNDSeed().
#         X   -   finite sample, array[N] (can be larger, in this  case only
#                 leading N elements are used). THIS ARRAY MUST BE SORTED BY
#                 ASCENDING.
#         N   -   number of elements to use, N>=1
# 
# RESULT
#     this function returns random number from continuous distribution which
#     tries to approximate X as mush as possible. min(X)<=Result<=max(X).
# 
#   -- ALGLIB --
#      Copyright 08.11.2011 by Bochkanov Sergey
#

SYNTAX: result = xalglib.hqrndcontinuous(state, x, n)

hqrnddiscrete function

#
# This function generates  random number from discrete distribution given by
# finite sample X.
# 
# INPUT PARAMETERS
#     State   -   high quality random number generator, must be
#                 initialized with HQRNDRandomize() or HQRNDSeed().
#         X   -   finite sample
#         N   -   number of elements to use, N>=1
# 
# RESULT
#     this function returns one of the X[i] for random i=0..N-1
# 
#   -- ALGLIB --
#      Copyright 08.11.2011 by Bochkanov Sergey
#

SYNTAX: result = xalglib.hqrnddiscrete(state, x, n)

hqrndexponential function

#
# Random number generator: exponential distribution
# 
# State structure must be initialized with HQRNDRandomize() or HQRNDSeed().
# 
#   -- ALGLIB --
#      Copyright 11.08.2007 by Bochkanov Sergey
#

SYNTAX: result = xalglib.hqrndexponential(state, lambdav)

hqrndnormal function

#
# Random number generator: normal numbers
# 
# This function generates one random number from normal distribution.
# Its performance is equal to that of HQRNDNormal2()
# 
# State structure must be initialized with HQRNDRandomize() or HQRNDSeed().
# 
#   -- ALGLIB --
#      Copyright 02.12.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.hqrndnormal(state)

hqrndnormal2 function

#
# Random number generator: normal numbers
# 
# This function generates two independent random numbers from normal
# distribution. Its performance is equal to that of HQRNDNormal()
# 
# State structure must be initialized with HQRNDRandomize() or HQRNDSeed().
# 
#   -- ALGLIB --
#      Copyright 02.12.2009 by Bochkanov Sergey
#

SYNTAX: x1, x2 = xalglib.hqrndnormal2(state)

hqrndrandomize function

#
# HQRNDState  initialization  with  random  values  which come from standard
# RNG.
# 
#   -- ALGLIB --
#      Copyright 02.12.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.hqrndrandomize()

hqrndseed function

#
# HQRNDState initialization with seed values
# 
#   -- ALGLIB --
#      Copyright 02.12.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.hqrndseed(s1, s2)

hqrnduniformi function

#
# This function generates random integer number in [0, N)
# 
# 1. State structure must be initialized with HQRNDRandomize() or HQRNDSeed()
# 2. N can be any positive number except for very large numbers:
#    * close to 2^31 on 32-bit systems
#    * close to 2^62 on 64-bit systems
#    An exception will be generated if N is too large.
# 
#   -- ALGLIB --
#      Copyright 02.12.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.hqrnduniformi(state, n)

hqrnduniformr function

#
# This function generates random real number in (0,1),
# not including interval boundaries
# 
# State structure must be initialized with HQRNDRandomize() or HQRNDSeed().
# 
#   -- ALGLIB --
#      Copyright 02.12.2009 by Bochkanov Sergey
#

SYNTAX: result = xalglib.hqrnduniformr(state)

hqrndunit2 function

#
# Random number generator: random X and Y such that X^2+Y^2=1
# 
# State structure must be initialized with HQRNDRandomize() or HQRNDSeed().
# 
#   -- ALGLIB --
#      Copyright 02.12.2009 by Bochkanov Sergey
#

SYNTAX: x, y = xalglib.hqrndunit2(state)

ibetaf module

incompletebeta function

#
# Incomplete beta integral
# 
# Returns incomplete beta integral of the arguments, evaluated
# from zero to x.  The function is defined as
# 
#                  x
#     -            -
#    | (a+b)      | |  a-1     b-1
#  -----------    |   t   (1-t)   dt.
#   -     -     | |
#  | (a) | (b)   -
#                 0
# 
# The domain of definition is 0 <= x <= 1.  In this
# implementation a and b are restricted to positive values.
# The integral from x to 1 may be obtained by the symmetry
# relation
# 
#    1 - incbet( a, b, x )  =  incbet( b, a, 1-x ).
# 
# The integral is evaluated by a continued fraction expansion
# or, when b*x is small, by a power series.
# 
# ACCURACY:
# 
# Tested at uniformly distributed random points (a,b,x) with a and b
# in "domain" and x between 0 and 1.
#                                        Relative error
# arithmetic   domain     # trials      peak         rms
#    IEEE      0,5         10000       6.9e-15     4.5e-16
#    IEEE      0,85       250000       2.2e-13     1.7e-14
#    IEEE      0,1000      30000       5.3e-12     6.3e-13
#    IEEE      0,10000    250000       9.3e-11     7.1e-12
#    IEEE      0,100000    10000       8.7e-10     4.8e-11
# Outputs smaller than the IEEE gradual underflow threshold
# were excluded from these statistics.
# 
# Cephes Math Library, Release 2.8:  June, 2000
# Copyright 1984, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.incompletebeta(a, b, x)

invincompletebeta function

#
# Inverse of imcomplete beta integral
# 
# Given y, the function finds x such that
# 
#  incbet( a, b, x ) = y .
# 
# The routine performs interval halving or Newton iterations to find the
# root of incbet(a,b,x) - y = 0.
# 
# 
# ACCURACY:
# 
#                      Relative error:
#                x     a,b
# arithmetic   domain  domain  # trials    peak       rms
#    IEEE      0,1    .5,10000   50000    5.8e-12   1.3e-13
#    IEEE      0,1   .25,100    100000    1.8e-13   3.9e-15
#    IEEE      0,1     0,5       50000    1.1e-12   5.5e-15
# With a and b constrained to half-integer or integer values:
#    IEEE      0,1    .5,10000   50000    5.8e-12   1.1e-13
#    IEEE      0,1    .5,100    100000    1.7e-14   7.9e-16
# With a = .5, b constrained to half-integer or integer values:
#    IEEE      0,1    .5,10000   10000    8.3e-11   1.0e-11
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1996, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.invincompletebeta(a, b, y)

idwint module

idwinterpolant class

#
# IDW interpolant.
#

class idwinterpolant(object):
    ...

idwbuildmodifiedshepard function

#
# IDW interpolant using modified Shepard method for uniform point
# distributions.
# 
# INPUT PARAMETERS:
#     XY  -   X and Y values, array[0..N-1,0..NX].
#             First NX columns contain X-values, last column contain
#             Y-values.
#     N   -   number of nodes, N>0.
#     NX  -   space dimension, NX>=1.
#     D   -   nodal function type, either:
#             * 0     constant  model.  Just  for  demonstration only, worst
#                     model ever.
#             * 1     linear model, least squares fitting. Simpe  model  for
#                     datasets too small for quadratic models
#             * 2     quadratic  model,  least  squares  fitting. Best model
#                     available (if your dataset is large enough).
#             * -1    "fast"  linear  model,  use  with  caution!!!   It  is
#                     significantly  faster than linear/quadratic and better
#                     than constant model. But it is less robust (especially
#                     in the presence of noise).
#     NQ  -   number of points used to calculate  nodal  functions  (ignored
#             for constant models). NQ should be LARGER than:
#             * max(1.5*(1+NX),2^NX+1) for linear model,
#             * max(3/4*(NX+2)*(NX+1),2^NX+1) for quadratic model.
#             Values less than this threshold will be silently increased.
#     NW  -   number of points used to calculate weights and to interpolate.
#             Required: >=2^NX+1, values less than this  threshold  will  be
#             silently increased.
#             Recommended value: about 2*NQ
# 
# OUTPUT PARAMETERS:
#     Z   -   IDW interpolant.
# 
# NOTES:
#   * best results are obtained with quadratic models, worst - with constant
#     models
#   * when N is large, NQ and NW must be significantly smaller than  N  both
#     to obtain optimal performance and to obtain optimal accuracy. In 2  or
#     3-dimensional tasks NQ=15 and NW=25 are good values to start with.
#   * NQ  and  NW  may  be  greater  than  N.  In  such  cases  they will be
#     automatically decreased.
#   * this subroutine is always succeeds (as long as correct parameters  are
#     passed).
#   * see  'Multivariate  Interpolation  of Large Sets of Scattered Data' by
#     Robert J. Renka for more information on this algorithm.
#   * this subroutine assumes that point distribution is uniform at the small
#     scales.  If  it  isn't  -  for  example,  points are concentrated along
#     "lines", but "lines" distribution is uniform at the larger scale - then
#     you should use IDWBuildModifiedShepardR()
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 02.03.2010 by Bochkanov Sergey
#

SYNTAX: z = xalglib.idwbuildmodifiedshepard(xy, n, nx, d, nq, nw)

idwbuildmodifiedshepardr function

#
# IDW interpolant using modified Shepard method for non-uniform datasets.
# 
# This type of model uses  constant  nodal  functions and interpolates using
# all nodes which are closer than user-specified radius R. It  may  be  used
# when points distribution is non-uniform at the small scale, but it  is  at
# the distances as large as R.
# 
# INPUT PARAMETERS:
#     XY  -   X and Y values, array[0..N-1,0..NX].
#             First NX columns contain X-values, last column contain
#             Y-values.
#     N   -   number of nodes, N>0.
#     NX  -   space dimension, NX>=1.
#     R   -   radius, R>0
# 
# OUTPUT PARAMETERS:
#     Z   -   IDW interpolant.
# 
# NOTES:
# * if there is less than IDWKMin points within  R-ball,  algorithm  selects
#   IDWKMin closest ones, so that continuity properties of  interpolant  are
#   preserved even far from points.
# 
#   -- ALGLIB PROJECT --
#      Copyright 11.04.2010 by Bochkanov Sergey
#

SYNTAX: z = xalglib.idwbuildmodifiedshepardr(xy, n, nx, r)

idwbuildnoisy function

#
# IDW model for noisy data.
# 
# This subroutine may be used to handle noisy data, i.e. data with noise  in
# OUTPUT values.  It differs from IDWBuildModifiedShepard() in the following
# aspects:
# * nodal functions are not constrained to pass through  nodes:  Qi(xi)<>yi,
#   i.e. we have fitting  instead  of  interpolation.
# * weights which are used during least  squares fitting stage are all equal
#   to 1.0 (independently of distance)
# * "fast"-linear or constant nodal functions are not supported (either  not
#   robust enough or too rigid)
# 
# This problem require far more complex tuning than interpolation  problems.
# Below you can find some recommendations regarding this problem:
# * focus on tuning NQ; it controls noise reduction. As for NW, you can just
#   make it equal to 2*NQ.
# * you can use cross-validation to determine optimal NQ.
# * optimal NQ is a result of complex tradeoff  between  noise  level  (more
#   noise = larger NQ required) and underlying  function  complexity  (given
#   fixed N, larger NQ means smoothing of compex features in the data).  For
#   example, NQ=N will reduce noise to the minimum level possible,  but  you
#   will end up with just constant/linear/quadratic (depending on  D)  least
#   squares model for the whole dataset.
# 
# INPUT PARAMETERS:
#     XY  -   X and Y values, array[0..N-1,0..NX].
#             First NX columns contain X-values, last column contain
#             Y-values.
#     N   -   number of nodes, N>0.
#     NX  -   space dimension, NX>=1.
#     D   -   nodal function degree, either:
#             * 1     linear model, least squares fitting. Simpe  model  for
#                     datasets too small for quadratic models (or  for  very
#                     noisy problems).
#             * 2     quadratic  model,  least  squares  fitting. Best model
#                     available (if your dataset is large enough).
#     NQ  -   number of points used to calculate nodal functions.  NQ should
#             be  significantly   larger   than  1.5  times  the  number  of
#             coefficients in a nodal function to overcome effects of noise:
#             * larger than 1.5*(1+NX) for linear model,
#             * larger than 3/4*(NX+2)*(NX+1) for quadratic model.
#             Values less than this threshold will be silently increased.
#     NW  -   number of points used to calculate weights and to interpolate.
#             Required: >=2^NX+1, values less than this  threshold  will  be
#             silently increased.
#             Recommended value: about 2*NQ or larger
# 
# OUTPUT PARAMETERS:
#     Z   -   IDW interpolant.
# 
# NOTES:
#   * best results are obtained with quadratic models, linear models are not
#     recommended to use unless you are pretty sure that it is what you want
#   * this subroutine is always succeeds (as long as correct parameters  are
#     passed).
#   * see  'Multivariate  Interpolation  of Large Sets of Scattered Data' by
#     Robert J. Renka for more information on this algorithm.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 02.03.2010 by Bochkanov Sergey
#

SYNTAX: z = xalglib.idwbuildnoisy(xy, n, nx, d, nq, nw)

idwcalc function

#
# IDW interpolation
# 
# INPUT PARAMETERS:
#     Z   -   IDW interpolant built with one of model building
#             subroutines.
#     X   -   array[0..NX-1], interpolation point
# 
# Result:
#     IDW interpolant Z(X)
# 
#   -- ALGLIB --
#      Copyright 02.03.2010 by Bochkanov Sergey
#

SYNTAX: result = xalglib.idwcalc(z, x)

igammaf module

incompletegamma function

#
# Incomplete gamma integral
# 
# The function is defined by
# 
#                           x
#                            -
#                   1       | |  -t  a-1
#  igam(a,x)  =   -----     |   e   t   dt.
#                  -      | |
#                 | (a)    -
#                           0
# 
# 
# In this implementation both arguments must be positive.
# The integral is evaluated by either a power series or
# continued fraction expansion, depending on the relative
# values of a and x.
# 
# ACCURACY:
# 
#                      Relative error:
# arithmetic   domain     # trials      peak         rms
#    IEEE      0,30       200000       3.6e-14     2.9e-15
#    IEEE      0,100      300000       9.9e-14     1.5e-14
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1985, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.incompletegamma(a, x)

incompletegammac function

#
# Complemented incomplete gamma integral
# 
# The function is defined by
# 
# 
#  igamc(a,x)   =   1 - igam(a,x)
# 
#                            inf.
#                              -
#                     1       | |  -t  a-1
#               =   -----     |   e   t   dt.
#                    -      | |
#                   | (a)    -
#                             x
# 
# 
# In this implementation both arguments must be positive.
# The integral is evaluated by either a power series or
# continued fraction expansion, depending on the relative
# values of a and x.
# 
# ACCURACY:
# 
# Tested at random a, x.
#                a         x                      Relative error:
# arithmetic   domain   domain     # trials      peak         rms
#    IEEE     0.5,100   0,100      200000       1.9e-14     1.7e-15
#    IEEE     0.01,0.5  0,100      200000       1.4e-13     1.6e-15
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1985, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.incompletegammac(a, x)

invincompletegammac function

#
# Inverse of complemented imcomplete gamma integral
# 
# Given p, the function finds x such that
# 
#  igamc( a, x ) = p.
# 
# Starting with the approximate value
# 
#         3
#  x = a t
# 
#  where
# 
#  t = 1 - d - ndtri(p) sqrt(d)
# 
# and
# 
#  d = 1/9a,
# 
# the routine performs up to 10 Newton iterations to find the
# root of igamc(a,x) - p = 0.
# 
# ACCURACY:
# 
# Tested at random a, p in the intervals indicated.
# 
#                a        p                      Relative error:
# arithmetic   domain   domain     # trials      peak         rms
#    IEEE     0.5,100   0,0.5       100000       1.0e-14     1.7e-15
#    IEEE     0.01,0.5  0,0.5       100000       9.0e-14     3.4e-15
#    IEEE    0.5,10000  0,0.5        20000       2.3e-13     3.8e-14
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier
#

SYNTAX: result = xalglib.invincompletegammac(a, y0)

inverseupdate module

rmatrixinvupdatecolumn function

#
# Inverse matrix update by the Sherman-Morrison formula
# 
# The algorithm updates matrix A^-1 when adding a vector to a column
# of matrix A.
# 
# Input parameters:
#     InvA        -   inverse of matrix A.
#                     Array whose indexes range within [0..N-1, 0..N-1].
#     N           -   size of matrix A.
#     UpdColumn   -   the column of A whose vector U was added.
#                     0 <= UpdColumn <= N-1
#     U           -   the vector to be added to a column.
#                     Array whose index ranges within [0..N-1].
# 
# Output parameters:
#     InvA        -   inverse of modified matrix A.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: inva = xalglib.rmatrixinvupdatecolumn(inva, n, updcolumn, u)

rmatrixinvupdaterow function

#
# Inverse matrix update by the Sherman-Morrison formula
# 
# The algorithm updates matrix A^-1 when adding a vector to a row
# of matrix A.
# 
# Input parameters:
#     InvA    -   inverse of matrix A.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     UpdRow  -   the row of A whose vector V was added.
#                 0 <= Row <= N-1
#     V       -   the vector to be added to a row.
#                 Array whose index ranges within [0..N-1].
# 
# Output parameters:
#     InvA    -   inverse of modified matrix A.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: inva = xalglib.rmatrixinvupdaterow(inva, n, updrow, v)

rmatrixinvupdatesimple function

#
# Inverse matrix update by the Sherman-Morrison formula
# 
# The algorithm updates matrix A^-1 when adding a number to an element
# of matrix A.
# 
# Input parameters:
#     InvA    -   inverse of matrix A.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     UpdRow  -   row where the element to be updated is stored.
#     UpdColumn - column where the element to be updated is stored.
#     UpdVal  -   a number to be added to the element.
# 
# 
# Output parameters:
#     InvA    -   inverse of modified matrix A.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: inva = xalglib.rmatrixinvupdatesimple(inva, n, updrow, updcolumn, updval)

rmatrixinvupdateuv function

#
# Inverse matrix update by the Sherman-Morrison formula
# 
# The algorithm computes the inverse of matrix A+u*v' by using the given matrix
# A^-1 and the vectors u and v.
# 
# Input parameters:
#     InvA    -   inverse of matrix A.
#                 Array whose indexes range within [0..N-1, 0..N-1].
#     N       -   size of matrix A.
#     U       -   the vector modifying the matrix.
#                 Array whose index ranges within [0..N-1].
#     V       -   the vector modifying the matrix.
#                 Array whose index ranges within [0..N-1].
# 
# Output parameters:
#     InvA - inverse of matrix A + u*v'.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: inva = xalglib.rmatrixinvupdateuv(inva, n, u, v)

jacobianelliptic module

jacobianellipticfunctions function

#
# Jacobian Elliptic Functions
# 
# Evaluates the Jacobian elliptic functions sn(u|m), cn(u|m),
# and dn(u|m) of parameter m between 0 and 1, and real
# argument u.
# 
# These functions are periodic, with quarter-period on the
# real axis equal to the complete elliptic integral
# ellpk(1.0-m).
# 
# Relation to incomplete elliptic integral:
# If u = ellik(phi,m), then sn(u|m) = sin(phi),
# and cn(u|m) = cos(phi).  Phi is called the amplitude of u.
# 
# Computation is by means of the arithmetic-geometric mean
# algorithm, except when m is within 1e-9 of 0 or 1.  In the
# latter case with m close to 1, the approximation applies
# only for phi < pi/2.
# 
# ACCURACY:
# 
# Tested at random points with u between 0 and 10, m between
# 0 and 1.
# 
#            Absolute error (* = relative error):
# arithmetic   function   # trials      peak         rms
#    IEEE      phi         10000       9.2e-16*    1.4e-16*
#    IEEE      sn          50000       4.1e-15     4.6e-16
#    IEEE      cn          40000       3.6e-15     4.4e-16
#    IEEE      dn          10000       1.3e-12     1.8e-14
# 
#  Peak error observed in consistency check using addition
# theorem for sn(u+v) was 4e-16 (absolute).  Also tested by
# the above relation to the incomplete elliptic integral.
# Accuracy deteriorates when u is large.
# 
# Cephes Math Library Release 2.8:  June, 2000
# Copyright 1984, 1987, 2000 by Stephen L. Moshier
#

SYNTAX: sn, cn, dn, ph = xalglib.jacobianellipticfunctions(u, m)

jarquebera module

jarqueberatest function

#
# Jarque-Bera test
# 
# This test checks hypotheses about the fact that a  given  sample  X  is  a
# sample of normal random variable.
# 
# Requirements:
#     * the number of elements in the sample is not less than 5.
# 
# Input parameters:
#     X   -   sample. Array whose index goes from 0 to N-1.
#     N   -   size of the sample. N>=5
# 
# Output parameters:
#     P           -   p-value for the test
# 
# Accuracy of the approximation used (5<=N<=1951):
# 
# p-value  	    relative error (5<=N<=1951)
# [1, 0.1]            < 1%
# [0.1, 0.01]         < 2%
# [0.01, 0.001]       < 6%
# [0.001, 0]          wasn't measured
# 
# For N>1951 accuracy wasn't measured but it shouldn't be sharply  different
# from table values.
# 
#   -- ALGLIB --
#      Copyright 09.04.2007 by Bochkanov Sergey
#

SYNTAX: p = xalglib.jarqueberatest(x, n)

laguerre module

laguerrecalculate function

#
# Calculation of the value of the Laguerre polynomial.
# 
# Parameters:
#     n   -   degree, n>=0
#     x   -   argument
# 
# Result:
#     the value of the Laguerre polynomial Ln at x
#

SYNTAX: result = xalglib.laguerrecalculate(n, x)

laguerrecoefficients function

#
# Representation of Ln as C[0] + C[1]*X + ... + C[N]*X^N
# 
# Input parameters:
#     N   -   polynomial degree, n>=0
# 
# Output parameters:
#     C   -   coefficients
#

SYNTAX: c = xalglib.laguerrecoefficients(n)

laguerresum function

#
# Summation of Laguerre polynomials using Clenshaw's recurrence formula.
# 
# This routine calculates c[0]*L0(x) + c[1]*L1(x) + ... + c[N]*LN(x)
# 
# Parameters:
#     n   -   degree, n>=0
#     x   -   argument
# 
# Result:
#     the value of the Laguerre polynomial at x
#

SYNTAX: result = xalglib.laguerresum(c, n, x)

lda module

fisherlda function

#
# Multiclass Fisher LDA
# 
# Subroutine finds coefficients of linear combination which optimally separates
# training set on classes.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two important  improvements   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison. Best results are achieved  for  high-dimensional  problems
#   ! (NVars is at least 256).
#   !
#   ! Multithreading is used to  accelerate  initial  phase  of  LDA,  which
#   ! includes calculation of products of large matrices.  Again,  for  best
#   ! efficiency problem must be high-dimensional.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     XY          -   training set, array[0..NPoints-1,0..NVars].
#                     First NVars columns store values of independent
#                     variables, next column stores number of class (from 0
#                     to NClasses-1) which dataset element belongs to. Fractional
#                     values are rounded to nearest integer.
#     NPoints     -   training set size, NPoints>=0
#     NVars       -   number of independent variables, NVars>=1
#     NClasses    -   number of classes, NClasses>=2
# 
# 
# OUTPUT PARAMETERS:
#     Info        -   return code:
#                     * -4, if internal EVD subroutine hasn't converged
#                     * -2, if there is a point with class number
#                           outside of [0..NClasses-1].
#                     * -1, if incorrect parameters was passed (NPoints<0,
#                           NVars<1, NClasses<2)
#                     *  1, if task has been solved
#                     *  2, if there was a multicollinearity in training set,
#                           but task has been solved.
#     W           -   linear combination coefficients, array[0..NVars-1]
# 
#   -- ALGLIB --
#      Copyright 31.05.2008 by Bochkanov Sergey
#

SYNTAX: info, w = xalglib.fisherlda(xy, npoints, nvars, nclasses)

fisherldan function

#
# N-dimensional multiclass Fisher LDA
# 
# Subroutine finds coefficients of linear combinations which optimally separates
# training set on classes. It returns N-dimensional basis whose vector are sorted
# by quality of training set separation (in descending order).
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two important  improvements   of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison. Best results are achieved  for  high-dimensional  problems
#   ! (NVars is at least 256).
#   !
#   ! Multithreading is used to  accelerate  initial  phase  of  LDA,  which
#   ! includes calculation of products of large matrices.  Again,  for  best
#   ! efficiency problem must be high-dimensional.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     XY          -   training set, array[0..NPoints-1,0..NVars].
#                     First NVars columns store values of independent
#                     variables, next column stores number of class (from 0
#                     to NClasses-1) which dataset element belongs to. Fractional
#                     values are rounded to nearest integer.
#     NPoints     -   training set size, NPoints>=0
#     NVars       -   number of independent variables, NVars>=1
#     NClasses    -   number of classes, NClasses>=2
# 
# 
# OUTPUT PARAMETERS:
#     Info        -   return code:
#                     * -4, if internal EVD subroutine hasn't converged
#                     * -2, if there is a point with class number
#                           outside of [0..NClasses-1].
#                     * -1, if incorrect parameters was passed (NPoints<0,
#                           NVars<1, NClasses<2)
#                     *  1, if task has been solved
#                     *  2, if there was a multicollinearity in training set,
#                           but task has been solved.
#     W           -   basis, array[0..NVars-1,0..NVars-1]
#                     columns of matrix stores basis vectors, sorted by
#                     quality of training set separation (in descending order)
# 
#   -- ALGLIB --
#      Copyright 31.05.2008 by Bochkanov Sergey
#

SYNTAX: info, w = xalglib.fisherldan(xy, npoints, nvars, nclasses)
SYNTAX: info, w = xalglib.smp_fisherldan(xy, npoints, nvars, nclasses)

legendre module

legendrecalculate function

#
# Calculation of the value of the Legendre polynomial Pn.
# 
# Parameters:
#     n   -   degree, n>=0
#     x   -   argument
# 
# Result:
#     the value of the Legendre polynomial Pn at x
#

SYNTAX: result = xalglib.legendrecalculate(n, x)

legendrecoefficients function

#
# Representation of Pn as C[0] + C[1]*X + ... + C[N]*X^N
# 
# Input parameters:
#     N   -   polynomial degree, n>=0
# 
# Output parameters:
#     C   -   coefficients
#

SYNTAX: c = xalglib.legendrecoefficients(n)

legendresum function

#
# Summation of Legendre polynomials using Clenshaw's recurrence formula.
# 
# This routine calculates
#     c[0]*P0(x) + c[1]*P1(x) + ... + c[N]*PN(x)
# 
# Parameters:
#     n   -   degree, n>=0
#     x   -   argument
# 
# Result:
#     the value of the Legendre polynomial at x
#

SYNTAX: result = xalglib.legendresum(c, n, x)

lincg module

lincgreport class

#
# 
#

class lincgreport(object):
    ...

lincgstate class

#
# This object stores state of the linear CG method.
# 
# You should use ALGLIB functions to work with this object.
# Never try to access its fields directly!
#

class lincgstate(object):
    ...

lincgcreate function

#
# This function initializes linear CG Solver. This solver is used  to  solve
# symmetric positive definite problems. If you want  to  solve  nonsymmetric
# (or non-positive definite) problem you may use LinLSQR solver provided  by
# ALGLIB.
# 
# USAGE:
# 1. User initializes algorithm state with LinCGCreate() call
# 2. User tunes solver parameters with  LinCGSetCond() and other functions
# 3. Optionally, user sets starting point with LinCGSetStartingPoint()
# 4. User  calls LinCGSolveSparse() function which takes algorithm state and
#    SparseMatrix object.
# 5. User calls LinCGResults() to get solution
# 6. Optionally, user may call LinCGSolveSparse()  again  to  solve  another
#    problem  with different matrix and/or right part without reinitializing
#    LinCGState structure.
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: state = xalglib.lincgcreate(n)

Examples:   [1]  

lincgresults function

#
# CG-solver: results.
# 
# This function must be called after LinCGSolve
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[N], solution
#     Rep     -   optimization report:
#                 * Rep.TerminationType completetion code:
#                     * -5    input matrix is either not positive definite,
#                             too large or too small
#                     * -4    overflow/underflow during solution
#                             (ill conditioned problem)
#                     *  1    ||residual||<=EpsF*||b||
#                     *  5    MaxIts steps was taken
#                     *  7    rounding errors prevent further progress,
#                             best point found is returned
#                 * Rep.IterationsCount contains iterations count
#                 * NMV countains number of matrix-vector calculations
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.lincgresults(state)

Examples:   [1]  

lincgsetcond function

#
# This function sets stopping criteria.
# 
# INPUT PARAMETERS:
#     EpsF    -   algorithm will be stopped if norm of residual is less than
#                 EpsF*||b||.
#     MaxIts  -   algorithm will be stopped if number of iterations is  more
#                 than MaxIts.
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTES:
# If  both  EpsF  and  MaxIts  are  zero then small EpsF will be set to small
# value.
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsetcond(state, epsf, maxits)

lincgsetprecdiag function

#
# This  function  changes  preconditioning  settings  of  LinCGSolveSparse()
# function.  LinCGSolveSparse() will use diagonal of the  system  matrix  as
# preconditioner. This preconditioning mode is active by default.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 19.11.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsetprecdiag(state)

lincgsetprecunit function

#
# This  function  changes  preconditioning  settings  of  LinCGSolveSparse()
# function. By default, SolveSparse() uses diagonal preconditioner,  but  if
# you want to use solver without preconditioning, you can call this function
# which forces solver to use unit matrix for preconditioning.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 19.11.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsetprecunit(state)

lincgsetrestartfreq function

#
# This function sets restart frequency. By default, algorithm  is  restarted
# after N subsequent iterations.
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsetrestartfreq(state, srf)

lincgsetrupdatefreq function

#
# This function sets frequency of residual recalculations.
# 
# Algorithm updates residual r_k using iterative formula,  but  recalculates
# it from scratch after each 10 iterations. It is done to avoid accumulation
# of numerical errors and to stop algorithm when r_k starts to grow.
# 
# Such low update frequence (1/10) gives very  little  overhead,  but  makes
# algorithm a bit more robust against numerical errors. However, you may
# change it
# 
# INPUT PARAMETERS:
#     Freq    -   desired update frequency, Freq>=0.
#                 Zero value means that no updates will be done.
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsetrupdatefreq(state, freq)

lincgsetstartingpoint function

#
# This function sets starting point.
# By default, zero starting point is used.
# 
# INPUT PARAMETERS:
#     X       -   starting point, array[N]
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsetstartingpoint(state, x)

lincgsetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# If NeedXRep is True, algorithm will call rep() callback function if  it is
# provided to MinCGOptimize().
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsetxrep(state, needxrep)

lincgsolvesparse function

#
# Procedure for solution of A*x=b with sparse A.
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
#     A       -   sparse matrix in the CRS format (you MUST contvert  it  to
#                 CRS format by calling SparseConvertToCRS() function).
#     IsUpper -   whether upper or lower triangle of A is used:
#                 * IsUpper=True  => only upper triangle is used and lower
#                                    triangle is not referenced at all
#                 * IsUpper=False => only lower triangle is used and upper
#                                    triangle is not referenced at all
#     B       -   right part, array[N]
# 
# RESULT:
#     This function returns no result.
#     You can get solution by calling LinCGResults()
# 
# NOTE: this function uses lightweight preconditioning -  multiplication  by
#       inverse of diag(A). If you want, you can turn preconditioning off by
#       calling LinCGSetPrecUnit(). However, preconditioning cost is low and
#       preconditioner  is  very  important  for  solution  of  badly scaled
#       problems.
# 
#   -- ALGLIB --
#      Copyright 14.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lincgsolvesparse(state, a, isupper, b)

Examples:   [1]  

lincg_d_1 example

import xalglib



#
# This example illustrates solution of sparse linear systems with
# conjugate gradient method.
# 
# Suppose that we have linear system A*x=b with sparse symmetric
# positive definite A (represented by sparsematrix object)
#         [ 5 1       ]
#         [ 1 7 2     ]
#     A = [   2 8 1   ]
#         [     1 4 1 ]
#         [       1 4 ]
# and right part b
#     [  7 ]
#     [ 17 ]
# b = [ 14 ]
#     [ 10 ]
#     [  6 ]
# and we want to solve this system using sparse linear CG. In order
# to do so, we have to create left part (sparsematrix object) and
# right part (dense array).
#
# Initially, sparse matrix is created in the Hash-Table format,
# which allows easy initialization, but do not allow matrix to be
# used in the linear solvers. So after construction you should convert
# sparse matrix to CRS format (one suited for linear operations).
#
# It is important to note that in our example we initialize full
# matrix A, both lower and upper triangles. However, it is symmetric
# and sparse solver needs just one half of the matrix. So you may
# save about half of the space by filling only one of the triangles.
#
a = xalglib.sparsecreate(5, 5)
xalglib.sparseset(a, 0, 0, 5.0)
xalglib.sparseset(a, 0, 1, 1.0)
xalglib.sparseset(a, 1, 0, 1.0)
xalglib.sparseset(a, 1, 1, 7.0)
xalglib.sparseset(a, 1, 2, 2.0)
xalglib.sparseset(a, 2, 1, 2.0)
xalglib.sparseset(a, 2, 2, 8.0)
xalglib.sparseset(a, 2, 3, 1.0)
xalglib.sparseset(a, 3, 2, 1.0)
xalglib.sparseset(a, 3, 3, 4.0)
xalglib.sparseset(a, 3, 4, 1.0)
xalglib.sparseset(a, 4, 3, 1.0)
xalglib.sparseset(a, 4, 4, 4.0)

#
# Now our matrix is fully initialized, but we have to do one more
# step - convert it from Hash-Table format to CRS format (see
# documentation on sparse matrices for more information about these
# formats).
#
# If you omit this call, ALGLIB will generate exception on the first
# attempt to use A in linear operations. 
#
xalglib.sparseconverttocrs(a)

#
# Initialization of the right part
#
b = [7,17,14,10,6]

#
# Now we have to create linear solver object and to use it for the
# solution of the linear system.
#
# NOTE: lincgsolvesparse() accepts additional parameter which tells
#       what triangle of the symmetric matrix should be used - upper
#       or lower. Because we've filled both parts of the matrix, we
#       can use any part - upper or lower.
#
s = xalglib.lincgcreate(5)
xalglib.lincgsolvesparse(s, a, True, b)
x, rep = xalglib.lincgresults(s)

print(rep.terminationtype) # expected 1
print(x) # expected [1.000,2.000,1.000,2.000,1.000]

linlsqr module

linlsqrreport class

#
# 
#

class linlsqrreport(object):
    ...

linlsqrstate class

#
# This object stores state of the LinLSQR method.
# 
# You should use ALGLIB functions to work with this object.
#

class linlsqrstate(object):
    ...

linlsqrcreate function

#
# This function initializes linear LSQR Solver. This solver is used to solve
# non-symmetric (and, possibly, non-square) problems. Least squares solution
# is returned for non-compatible systems.
# 
# USAGE:
# 1. User initializes algorithm state with LinLSQRCreate() call
# 2. User tunes solver parameters with  LinLSQRSetCond() and other functions
# 3. User  calls  LinLSQRSolveSparse()  function which takes algorithm state
#    and SparseMatrix object.
# 4. User calls LinLSQRResults() to get solution
# 5. Optionally, user may call LinLSQRSolveSparse() again to  solve  another
#    problem  with different matrix and/or right part without reinitializing
#    LinLSQRState structure.
# 
# INPUT PARAMETERS:
#     M       -   number of rows in A
#     N       -   number of variables, N>0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 30.11.2011 by Bochkanov Sergey
#

SYNTAX: state = xalglib.linlsqrcreate(m, n)

Examples:   [1]  

linlsqrresults function

#
# LSQR solver: results.
# 
# This function must be called after LinLSQRSolve
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[N], solution
#     Rep     -   optimization report:
#                 * Rep.TerminationType completetion code:
#                     *  1    ||Rk||<=EpsB*||B||
#                     *  4    ||A^T*Rk||/(||A||*||Rk||)<=EpsA
#                     *  5    MaxIts steps was taken
#                     *  7    rounding errors prevent further progress,
#                             X contains best point found so far.
#                             (sometimes returned on singular systems)
#                 * Rep.IterationsCount contains iterations count
#                 * NMV countains number of matrix-vector calculations
# 
#   -- ALGLIB --
#      Copyright 30.11.2011 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.linlsqrresults(state)

Examples:   [1]  

linlsqrsetcond function

#
# This function sets stopping criteria.
# 
# INPUT PARAMETERS:
#     EpsA    -   algorithm will be stopped if ||A^T*Rk||/(||A||*||Rk||)<=EpsA.
#     EpsB    -   algorithm will be stopped if ||Rk||<=EpsB*||B||
#     MaxIts  -   algorithm will be stopped if number of iterations
#                 more than MaxIts.
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTE: if EpsA,EpsB,EpsC and MaxIts are zero then these variables will
# be setted as default values.
# 
#   -- ALGLIB --
#      Copyright 30.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.linlsqrsetcond(state, epsa, epsb, maxits)

linlsqrsetlambdai function

#
# This function sets optional Tikhonov regularization coefficient.
# It is zero by default.
# 
# INPUT PARAMETERS:
#     LambdaI -   regularization factor, LambdaI>=0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 30.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.linlsqrsetlambdai(state, lambdai)

linlsqrsetprecdiag function

#
# This  function  changes  preconditioning  settings  of  LinCGSolveSparse()
# function.  LinCGSolveSparse() will use diagonal of the  system  matrix  as
# preconditioner. This preconditioning mode is active by default.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 19.11.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.linlsqrsetprecdiag(state)

linlsqrsetprecunit function

#
# This  function  changes  preconditioning  settings of LinLSQQSolveSparse()
# function. By default, SolveSparse() uses diagonal preconditioner,  but  if
# you want to use solver without preconditioning, you can call this function
# which forces solver to use unit matrix for preconditioning.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 19.11.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.linlsqrsetprecunit(state)

linlsqrsetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# If NeedXRep is True, algorithm will call rep() callback function if  it is
# provided to MinCGOptimize().
# 
#   -- ALGLIB --
#      Copyright 30.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.linlsqrsetxrep(state, needxrep)

linlsqrsolvesparse function

#
# Procedure for solution of A*x=b with sparse A.
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
#     A       -   sparse M*N matrix in the CRS format (you MUST contvert  it
#                 to CRS format  by  calling  SparseConvertToCRS()  function
#                 BEFORE you pass it to this function).
#     B       -   right part, array[M]
# 
# RESULT:
#     This function returns no result.
#     You can get solution by calling LinCGResults()
# 
# NOTE: this function uses lightweight preconditioning -  multiplication  by
#       inverse of diag(A). If you want, you can turn preconditioning off by
#       calling LinLSQRSetPrecUnit(). However, preconditioning cost is   low
#       and preconditioner is very important for solution  of  badly  scaled
#       problems.
# 
#   -- ALGLIB --
#      Copyright 30.11.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.linlsqrsolvesparse(state, a, b)

Examples:   [1]  

linlsqr_d_1 example

import xalglib



#
# This example illustrates solution of sparse linear least squares problem
# with LSQR algorithm.
# 
# Suppose that we have least squares problem min|A*x-b| with sparse A
# represented by sparsematrix object
#         [ 1 1 ]
#         [ 1 1 ]
#     A = [ 2 1 ]
#         [ 1   ]
#         [   1 ]
# and right part b
#     [ 4 ]
#     [ 2 ]
# b = [ 4 ]
#     [ 1 ]
#     [ 2 ]
# and we want to solve this system in the least squares sense using
# LSQR algorithm. In order to do so, we have to create left part
# (sparsematrix object) and right part (dense array).
#
# Initially, sparse matrix is created in the Hash-Table format,
# which allows easy initialization, but do not allow matrix to be
# used in the linear solvers. So after construction you should convert
# sparse matrix to CRS format (one suited for linear operations).
#
a = xalglib.sparsecreate(5, 2)
xalglib.sparseset(a, 0, 0, 1.0)
xalglib.sparseset(a, 0, 1, 1.0)
xalglib.sparseset(a, 1, 0, 1.0)
xalglib.sparseset(a, 1, 1, 1.0)
xalglib.sparseset(a, 2, 0, 2.0)
xalglib.sparseset(a, 2, 1, 1.0)
xalglib.sparseset(a, 3, 0, 1.0)
xalglib.sparseset(a, 4, 1, 1.0)

#
# Now our matrix is fully initialized, but we have to do one more
# step - convert it from Hash-Table format to CRS format (see
# documentation on sparse matrices for more information about these
# formats).
#
# If you omit this call, ALGLIB will generate exception on the first
# attempt to use A in linear operations. 
#
xalglib.sparseconverttocrs(a)

#
# Initialization of the right part
#
b = [4,2,4,1,2]

#
# Now we have to create linear solver object and to use it for the
# solution of the linear system.
#
s = xalglib.linlsqrcreate(5, 2)
xalglib.linlsqrsolvesparse(s, a, b)
x, rep = xalglib.linlsqrresults(s)

print(rep.terminationtype) # expected 4
print(x) # expected [1.000,2.000]

linreg module

linearmodel class

#
# 
#

class linearmodel(object):
    ...

lrreport class

#
# LRReport structure contains additional information about linear model:
# * C             -   covariation matrix,  array[0..NVars,0..NVars].
#                     C[i,j] = Cov(A[i],A[j])
# * RMSError      -   root mean square error on a training set
# * AvgError      -   average error on a training set
# * AvgRelError   -   average relative error on a training set (excluding
#                     observations with zero function value).
# * CVRMSError    -   leave-one-out cross-validation estimate of
#                     generalization error. Calculated using fast algorithm
#                     with O(NVars*NPoints) complexity.
# * CVAvgError    -   cross-validation estimate of average error
# * CVAvgRelError -   cross-validation estimate of average relative error
# 
# All other fields of the structure are intended for internal use and should
# not be used outside ALGLIB.
#

class lrreport(object):
    ...

lravgerror function

#
# Average error on the test set
# 
# INPUT PARAMETERS:
#     LM      -   linear model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     average error.
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.lravgerror(lm, xy, npoints)

lravgrelerror function

#
# RMS error on the test set
# 
# INPUT PARAMETERS:
#     LM      -   linear model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     average relative error.
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.lravgrelerror(lm, xy, npoints)

lrbuild function

#
# Linear regression
# 
# Subroutine builds model:
# 
#     Y = A(0)*X[0] + ... + A(N-1)*X[N-1] + A(N)
# 
# and model found in ALGLIB format, covariation matrix, training set  errors
# (rms,  average,  average  relative)   and  leave-one-out  cross-validation
# estimate of the generalization error. CV  estimate calculated  using  fast
# algorithm with O(NPoints*NVars) complexity.
# 
# When  covariation  matrix  is  calculated  standard deviations of function
# values are assumed to be equal to RMS error on the training set.
# 
# INPUT PARAMETERS:
#     XY          -   training set, array [0..NPoints-1,0..NVars]:
#                     * NVars columns - independent variables
#                     * last column - dependent variable
#     NPoints     -   training set size, NPoints>NVars+1
#     NVars       -   number of independent variables
# 
# OUTPUT PARAMETERS:
#     Info        -   return code:
#                     * -255, in case of unknown internal error
#                     * -4, if internal SVD subroutine haven't converged
#                     * -1, if incorrect parameters was passed (NPoints<NVars+2, NVars<1).
#                     *  1, if subroutine successfully finished
#     LM          -   linear model in the ALGLIB format. Use subroutines of
#                     this unit to work with the model.
#     AR          -   additional results
# 
# 
#   -- ALGLIB --
#      Copyright 02.08.2008 by Bochkanov Sergey
#

SYNTAX: info, lm, ar = xalglib.lrbuild(xy, npoints, nvars)

Examples:   [1]  

lrbuilds function

#
# Linear regression
# 
# Variant of LRBuild which uses vector of standatd deviations (errors in
# function values).
# 
# INPUT PARAMETERS:
#     XY          -   training set, array [0..NPoints-1,0..NVars]:
#                     * NVars columns - independent variables
#                     * last column - dependent variable
#     S           -   standard deviations (errors in function values)
#                     array[0..NPoints-1], S[i]>0.
#     NPoints     -   training set size, NPoints>NVars+1
#     NVars       -   number of independent variables
# 
# OUTPUT PARAMETERS:
#     Info        -   return code:
#                     * -255, in case of unknown internal error
#                     * -4, if internal SVD subroutine haven't converged
#                     * -1, if incorrect parameters was passed (NPoints<NVars+2, NVars<1).
#                     * -2, if S[I]<=0
#                     *  1, if subroutine successfully finished
#     LM          -   linear model in the ALGLIB format. Use subroutines of
#                     this unit to work with the model.
#     AR          -   additional results
# 
# 
#   -- ALGLIB --
#      Copyright 02.08.2008 by Bochkanov Sergey
#

SYNTAX: info, lm, ar = xalglib.lrbuilds(xy, s, npoints, nvars)

lrbuildz function

#
# Like LRBuild but builds model
# 
#     Y = A(0)*X[0] + ... + A(N-1)*X[N-1]
# 
# i.e. with zero constant term.
# 
#   -- ALGLIB --
#      Copyright 30.10.2008 by Bochkanov Sergey
#

SYNTAX: info, lm, ar = xalglib.lrbuildz(xy, npoints, nvars)

lrbuildzs function

#
# Like LRBuildS, but builds model
# 
#     Y = A(0)*X[0] + ... + A(N-1)*X[N-1]
# 
# i.e. with zero constant term.
# 
#   -- ALGLIB --
#      Copyright 30.10.2008 by Bochkanov Sergey
#

SYNTAX: info, lm, ar = xalglib.lrbuildzs(xy, s, npoints, nvars)

lrpack function

#
# "Packs" coefficients and creates linear model in ALGLIB format (LRUnpack
# reversed).
# 
# INPUT PARAMETERS:
#     V           -   coefficients, array[0..NVars]
#     NVars       -   number of independent variables
# 
# OUTPUT PAREMETERS:
#     LM          -   linear model.
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: lm = xalglib.lrpack(v, nvars)

lrprocess function

#
# Procesing
# 
# INPUT PARAMETERS:
#     LM      -   linear model
#     X       -   input vector,  array[0..NVars-1].
# 
# Result:
#     value of linear model regression estimate
# 
#   -- ALGLIB --
#      Copyright 03.09.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.lrprocess(lm, x)

lrrmserror function

#
# RMS error on the test set
# 
# INPUT PARAMETERS:
#     LM      -   linear model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     root mean square error.
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.lrrmserror(lm, xy, npoints)

lrunpack function

#
# Unpacks coefficients of linear model.
# 
# INPUT PARAMETERS:
#     LM          -   linear model in ALGLIB format
# 
# OUTPUT PARAMETERS:
#     V           -   coefficients, array[0..NVars]
#                     constant term (intercept) is stored in the V[NVars].
#     NVars       -   number of independent variables (one less than number
#                     of coefficients)
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: v, nvars = xalglib.lrunpack(lm)

Examples:   [1]  

linreg_d_basic example

import xalglib



#
# In this example we demonstrate linear fitting by f(x|a) = a*exp(0.5*x).
#
# We have:
# * xy - matrix of basic function values (exp(0.5*x)) and expected values
#
xy = [[0.606531,1.133719],[0.670320,1.306522],[0.740818,1.504604],[0.818731,1.554663],[0.904837,1.884638],[1.000000,2.072436],[1.105171,2.257285],[1.221403,2.534068],[1.349859,2.622017],[1.491825,2.897713],[1.648721,3.219371]]

info, model, rep = xalglib.lrbuildz(xy, 11, 1)
print(info) # expected 1
c, nvars = xalglib.lrunpack(model)
print(c) # expected [1.98650,0.00000]

logit module

logitmodel class

#
# 
#

class logitmodel(object):
    ...

mnlreport class

#
# MNLReport structure contains information about training process:
# * NGrad     -   number of gradient calculations
# * NHess     -   number of Hessian calculations
#

class mnlreport(object):
    ...

mnlavgce function

#
# Average cross-entropy (in bits per element) on the test set
# 
# INPUT PARAMETERS:
#     LM      -   logit model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     CrossEntropy/(NPoints*ln(2)).
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.mnlavgce(lm, xy, npoints)

mnlavgerror function

#
# Average error on the test set
# 
# INPUT PARAMETERS:
#     LM      -   logit model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     average error (error when estimating posterior probabilities).
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.mnlavgerror(lm, xy, npoints)

mnlavgrelerror function

#
# Average relative error on the test set
# 
# INPUT PARAMETERS:
#     LM      -   logit model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     average relative error (error when estimating posterior probabilities).
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.mnlavgrelerror(lm, xy, ssize)

mnlclserror function

#
# Classification error on test set = MNLRelClsError*NPoints
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.mnlclserror(lm, xy, npoints)

mnlpack function

#
# "Packs" coefficients and creates logit model in ALGLIB format (MNLUnpack
# reversed).
# 
# INPUT PARAMETERS:
#     A           -   model (see MNLUnpack)
#     NVars       -   number of independent variables
#     NClasses    -   number of classes
# 
# OUTPUT PARAMETERS:
#     LM          -   logit model.
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: lm = xalglib.mnlpack(a, nvars, nclasses)

mnlprocess function

#
# Procesing
# 
# INPUT PARAMETERS:
#     LM      -   logit model, passed by non-constant reference
#                 (some fields of structure are used as temporaries
#                 when calculating model output).
#     X       -   input vector,  array[0..NVars-1].
#     Y       -   (possibly) preallocated buffer; if size of Y is less than
#                 NClasses, it will be reallocated.If it is large enough, it
#                 is NOT reallocated, so we can save some time on reallocation.
# 
# OUTPUT PARAMETERS:
#     Y       -   result, array[0..NClasses-1]
#                 Vector of posterior probabilities for classification task.
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: y = xalglib.mnlprocess(lm, x, y)

mnlprocessi function

#
# 'interactive'  variant  of  MNLProcess  for  languages  like  Python which
# support constructs like "Y = MNLProcess(LM,X)" and interactive mode of the
# interpreter
# 
# This function allocates new array on each call,  so  it  is  significantly
# slower than its 'non-interactive' counterpart, but it is  more  convenient
# when you call it from command line.
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: y = xalglib.mnlprocessi(lm, x)

mnlrelclserror function

#
# Relative classification error on the test set
# 
# INPUT PARAMETERS:
#     LM      -   logit model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     percent of incorrectly classified cases.
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.mnlrelclserror(lm, xy, npoints)

mnlrmserror function

#
# RMS error on the test set
# 
# INPUT PARAMETERS:
#     LM      -   logit model
#     XY      -   test set
#     NPoints -   test set size
# 
# RESULT:
#     root mean square error (error when estimating posterior probabilities).
# 
#   -- ALGLIB --
#      Copyright 30.08.2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.mnlrmserror(lm, xy, npoints)

mnltrainh function

#
# This subroutine trains logit model.
# 
# INPUT PARAMETERS:
#     XY          -   training set, array[0..NPoints-1,0..NVars]
#                     First NVars columns store values of independent
#                     variables, next column stores number of class (from 0
#                     to NClasses-1) which dataset element belongs to. Fractional
#                     values are rounded to nearest integer.
#     NPoints     -   training set size, NPoints>=1
#     NVars       -   number of independent variables, NVars>=1
#     NClasses    -   number of classes, NClasses>=2
# 
# OUTPUT PARAMETERS:
#     Info        -   return code:
#                     * -2, if there is a point with class number
#                           outside of [0..NClasses-1].
#                     * -1, if incorrect parameters was passed
#                           (NPoints<NVars+2, NVars<1, NClasses<2).
#                     *  1, if task has been solved
#     LM          -   model built
#     Rep         -   training report
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: info, lm, rep = xalglib.mnltrainh(xy, npoints, nvars, nclasses)

mnlunpack function

#
# Unpacks coefficients of logit model. Logit model have form:
# 
#     P(class=i) = S(i) / (S(0) + S(1) + ... +S(M-1))
#           S(i) = Exp(A[i,0]*X[0] + ... + A[i,N-1]*X[N-1] + A[i,N]), when i<M-1
#         S(M-1) = 1
# 
# INPUT PARAMETERS:
#     LM          -   logit model in ALGLIB format
# 
# OUTPUT PARAMETERS:
#     V           -   coefficients, array[0..NClasses-2,0..NVars]
#     NVars       -   number of independent variables
#     NClasses    -   number of classes
# 
#   -- ALGLIB --
#      Copyright 10.09.2008 by Bochkanov Sergey
#

SYNTAX: a, nvars, nclasses = xalglib.mnlunpack(lm)

lsfit module

barycentricfitreport class

#
# Barycentric fitting report:
#     RMSError        RMS error
#     AvgError        average error
#     AvgRelError     average relative error (for non-zero Y[I])
#     MaxError        maximum error
#     TaskRCond       reciprocal of task's condition number
#

class barycentricfitreport(object):
    ...

lsfitreport class

#
# Least squares fitting report. This structure contains informational fields
# which are set by fitting functions provided by this unit.
# 
# Different functions initialize different sets of  fields,  so  you  should
# read documentation on specific function you used in order  to  know  which
# fields are initialized.
# 
#     TaskRCond       reciprocal of task's condition number
#     IterationsCount number of internal iterations
# 
#     VarIdx          if user-supplied gradient contains errors  which  were
#                     detected by nonlinear fitter, this  field  is  set  to
#                     index  of  the  first  component  of gradient which is
#                     suspected to be spoiled by bugs.
# 
#     RMSError        RMS error
#     AvgError        average error
#     AvgRelError     average relative error (for non-zero Y[I])
#     MaxError        maximum error
# 
#     WRMSError       weighted RMS error
# 
#     CovPar          covariance matrix for parameters, filled by some solvers
#     ErrPar          vector of errors in parameters, filled by some solvers
#     ErrCurve        vector of fit errors -  variability  of  the  best-fit
#                     curve, filled by some solvers.
#     Noise           vector of per-point noise estimates, filled by
#                     some solvers.
#     R2              coefficient of determination (non-weighted, non-adjusted),
#                     filled by some solvers.
#

class lsfitreport(object):
    ...

lsfitstate class

#
# Nonlinear fitter.
# 
# You should use ALGLIB functions to work with fitter.
# Never try to access its fields directly!
#

class lsfitstate(object):
    ...

polynomialfitreport class

#
# Polynomial fitting report:
#     TaskRCond       reciprocal of task's condition number
#     RMSError        RMS error
#     AvgError        average error
#     AvgRelError     average relative error (for non-zero Y[I])
#     MaxError        maximum error
#

class polynomialfitreport(object):
    ...

spline1dfitreport class

#
# Spline fitting report:
#     RMSError        RMS error
#     AvgError        average error
#     AvgRelError     average relative error (for non-zero Y[I])
#     MaxError        maximum error
# 
# Fields  below are  filled  by   obsolete    functions   (Spline1DFitCubic,
# Spline1DFitHermite). Modern fitting functions do NOT fill these fields:
#     TaskRCond       reciprocal of task's condition number
#

class spline1dfitreport(object):
    ...

barycentricfitfloaterhormann function

#
# Rational least squares fitting using  Floater-Hormann  rational  functions
# with optimal D chosen from [0,9].
# 
# Equidistant  grid  with M node on [min(x),max(x)]  is  used to build basis
# functions. Different values of D are tried, optimal  D  (least  root  mean
# square error) is chosen.  Task  is  linear, so linear least squares solver
# is used. Complexity  of  this  computational  scheme is  O(N*M^2)  (mostly
# dominated by the least squares solver).
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     N   -   number of points, N>0.
#     M   -   number of basis functions ( = number_of_nodes), M>=2.
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearWC() subroutine.
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD
#                         -3 means inconsistent constraints
#     B   -   barycentric interpolant.
#     Rep -   report, same format as in LSFitLinearWC() subroutine.
#             Following fields are set:
#             * DBest         best value of the D parameter
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
#   -- ALGLIB PROJECT --
#      Copyright 18.08.2009 by Bochkanov Sergey
#

SYNTAX: info, b, rep = xalglib.barycentricfitfloaterhormann(x, y, n, m)
SYNTAX: info, b, rep = xalglib.smp_barycentricfitfloaterhormann(x, y, n, m)

barycentricfitfloaterhormannwc function

#
# Weghted rational least  squares  fitting  using  Floater-Hormann  rational
# functions  with  optimal  D  chosen  from  [0,9],  with  constraints   and
# individual weights.
# 
# Equidistant  grid  with M node on [min(x),max(x)]  is  used to build basis
# functions. Different values of D are tried, optimal D (least WEIGHTED root
# mean square error) is chosen.  Task  is  linear,  so  linear least squares
# solver  is  used.  Complexity  of  this  computational  scheme is O(N*M^2)
# (mostly dominated by the least squares solver).
# 
# SEE ALSO
# * BarycentricFitFloaterHormann(), "lightweight" fitting without invididual
#   weights and constraints.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     W   -   weights, array[0..N-1]
#             Each summand in square  sum  of  approximation deviations from
#             given  values  is  multiplied  by  the square of corresponding
#             weight. Fill it by 1's if you don't  want  to  solve  weighted
#             task.
#     N   -   number of points, N>0.
#     XC  -   points where function values/derivatives are constrained,
#             array[0..K-1].
#     YC  -   values of constraints, array[0..K-1]
#     DC  -   array[0..K-1], types of constraints:
#             * DC[i]=0   means that S(XC[i])=YC[i]
#             * DC[i]=1   means that S'(XC[i])=YC[i]
#             SEE BELOW FOR IMPORTANT INFORMATION ON CONSTRAINTS
#     K   -   number of constraints, 0<=K<M.
#             K=0 means no constraints (XC/YC/DC are not used in such cases)
#     M   -   number of basis functions ( = number_of_nodes), M>=2.
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearWC() subroutine.
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD
#                         -3 means inconsistent constraints
#                         -1 means another errors in parameters passed
#                            (N<=0, for example)
#     B   -   barycentric interpolant.
#     Rep -   report, same format as in LSFitLinearWC() subroutine.
#             Following fields are set:
#             * DBest         best value of the D parameter
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroutine doesn't calculate task's condition number for K<>0.
# 
# SETTING CONSTRAINTS - DANGERS AND OPPORTUNITIES:
# 
# Setting constraints can lead  to undesired  results,  like ill-conditioned
# behavior, or inconsistency being detected. From the other side,  it allows
# us to improve quality of the fit. Here we summarize  our  experience  with
# constrained barycentric interpolants:
# * excessive  constraints  can  be  inconsistent.   Floater-Hormann   basis
#   functions aren't as flexible as splines (although they are very smooth).
# * the more evenly constraints are spread across [min(x),max(x)],  the more
#   chances that they will be consistent
# * the  greater  is  M (given  fixed  constraints),  the  more chances that
#   constraints will be consistent
# * in the general case, consistency of constraints IS NOT GUARANTEED.
# * in the several special cases, however, we CAN guarantee consistency.
# * one of this cases is constraints on the function  VALUES at the interval
#   boundaries. Note that consustency of the  constraints  on  the  function
#   DERIVATIVES is NOT guaranteed (you can use in such cases  cubic  splines
#   which are more flexible).
# * another  special  case  is ONE constraint on the function value (OR, but
#   not AND, derivative) anywhere in the interval
# 
# Our final recommendation is to use constraints  WHEN  AND  ONLY  WHEN  you
# can't solve your task without them. Anything beyond  special  cases  given
# above is not guaranteed and may result in inconsistency.
# 
#   -- ALGLIB PROJECT --
#      Copyright 18.08.2009 by Bochkanov Sergey
#

SYNTAX: info, b, rep = xalglib.barycentricfitfloaterhormannwc(x, y, w, n, xc, yc, dc, k, m)
SYNTAX: info, b, rep = xalglib.smp_barycentricfitfloaterhormannwc(x, y, w, n, xc, yc, dc, k, m)

logisticcalc4 function

#
# This function calculates value of four-parameter logistic (4PL)  model  at
# specified point X. 4PL model has following form:
# 
#     F(x|A,B,C,D) = D+(A-D)/(1+Power(x/C,B))
# 
# INPUT PARAMETERS:
#     X       -   current point, X>=0:
#                 * zero X is correctly handled even for B<=0
#                 * negative X results in exception.
#     A, B, C, D- parameters of 4PL model:
#                 * A is unconstrained
#                 * B is unconstrained; zero or negative values are handled
#                   correctly.
#                 * C>0, non-positive value results in exception
#                 * D is unconstrained
# 
# RESULT:
#     model value at X
# 
# NOTE: if B=0, denominator is assumed to be equal to 2.0 even  for  zero  X
#       (strictly speaking, 0^0 is undefined).
# 
# NOTE: this function also throws exception  if  all  input  parameters  are
#       correct, but overflow was detected during calculations.
# 
# NOTE: this function performs a lot of checks;  if  you  need  really  high
#       performance, consider evaluating model  yourself,  without  checking
#       for degenerate cases.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 14.05.2014 by Bochkanov Sergey
#

SYNTAX: result = xalglib.logisticcalc4(x, a, b, c, d)

Examples:   [1]  

logisticcalc5 function

#
# This function calculates value of five-parameter logistic (5PL)  model  at
# specified point X. 5PL model has following form:
# 
#     F(x|A,B,C,D,G) = D+(A-D)/Power(1+Power(x/C,B),G)
# 
# INPUT PARAMETERS:
#     X       -   current point, X>=0:
#                 * zero X is correctly handled even for B<=0
#                 * negative X results in exception.
#     A, B, C, D, G- parameters of 5PL model:
#                 * A is unconstrained
#                 * B is unconstrained; zero or negative values are handled
#                   correctly.
#                 * C>0, non-positive value results in exception
#                 * D is unconstrained
#                 * G>0, non-positive value results in exception
# 
# RESULT:
#     model value at X
# 
# NOTE: if B=0, denominator is assumed to be equal to Power(2.0,G) even  for
#       zero X (strictly speaking, 0^0 is undefined).
# 
# NOTE: this function also throws exception  if  all  input  parameters  are
#       correct, but overflow was detected during calculations.
# 
# NOTE: this function performs a lot of checks;  if  you  need  really  high
#       performance, consider evaluating model  yourself,  without  checking
#       for degenerate cases.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 14.05.2014 by Bochkanov Sergey
#

SYNTAX: result = xalglib.logisticcalc5(x, a, b, c, d, g)

Examples:   [1]  

logisticfit4 function

#
# This function fits four-parameter logistic (4PL) model  to  data  provided
# by user. 4PL model has following form:
# 
#     F(x|A,B,C,D) = D+(A-D)/(1+Power(x/C,B))
# 
# Here:
#     * A, D - unconstrained (see LogisticFit4EC() for constrained 4PL)
#     * B>=0
#     * C>0
# 
# IMPORTANT: output of this function is constrained in  such  way that  B>0.
#            Because 4PL model is symmetric with respect to B, there  is  no
#            need to explore  B<0.  Constraining  B  makes  algorithm easier
#            to stabilize and debug.
#            Users  who  for  some  reason  prefer to work with negative B's
#            should transform output themselves (swap A and D, replace B  by
#            -B).
# 
# 4PL fitting is implemented as follows:
# * we perform small number of restarts from random locations which helps to
#   solve problem of bad local extrema. Locations are only partially  random
#   - we use input data to determine good  initial  guess,  but  we  include
#   controlled amount of randomness.
# * we perform Levenberg-Marquardt fitting with very  tight  constraints  on
#   parameters B and C - it allows us to find good  initial  guess  for  the
#   second stage without risk of running into "flat spot".
# * second  Levenberg-Marquardt  round  is   performed   without   excessive
#   constraints. Results from the previous round are used as initial guess.
# * after fitting is done, we compare results with best values found so far,
#   rewrite "best solution" if needed, and move to next random location.
# 
# Overall algorithm is very stable and is not prone to  bad  local  extrema.
# Furthermore, it automatically scales when input data have  very  large  or
# very small range.
# 
# INPUT PARAMETERS:
#     X       -   array[N], stores X-values.
#                 MUST include only non-negative numbers  (but  may  include
#                 zero values). Can be unsorted.
#     Y       -   array[N], values to fit.
#     N       -   number of points. If N is less than  length  of  X/Y, only
#                 leading N elements are used.
# 
# OUTPUT PARAMETERS:
#     A, B, C, D- parameters of 4PL model
#     Rep     -   fitting report. This structure has many fields,  but  ONLY
#                 ONES LISTED BELOW ARE SET:
#                 * Rep.IterationsCount - number of iterations performed
#                 * Rep.RMSError - root-mean-square error
#                 * Rep.AvgError - average absolute error
#                 * Rep.AvgRelError - average relative error (calculated for
#                   non-zero Y-values)
#                 * Rep.MaxError - maximum absolute error
#                 * Rep.R2 - coefficient of determination,  R-squared.  This
#                   coefficient   is  calculated  as  R2=1-RSS/TSS  (in case
#                   of nonlinear  regression  there  are  multiple  ways  to
#                   define R2, each of them giving different results).
# 
# NOTE: after  you  obtained  coefficients,  you  can  evaluate  model  with
#       LogisticCalc4() function.
# 
# NOTE: if you need better control over fitting process than provided by this
#       function, you may use LogisticFit45X().
# 
# NOTE: step is automatically scaled according to scale of parameters  being
#       fitted before we compare its length with EpsX. Thus,  this  function
#       can be used to fit data with very small or very large values without
#       changing EpsX.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 14.02.2014 by Bochkanov Sergey
#

SYNTAX: a, b, c, d, rep = xalglib.logisticfit4(x, y, n)

Examples:   [1]  

logisticfit45x function

#
# This is "expert" 4PL/5PL fitting function, which can be used if  you  need
# better control over fitting process than provided  by  LogisticFit4()  or
# LogisticFit5().
# 
# This function fits model of the form
# 
#     F(x|A,B,C,D)   = D+(A-D)/(1+Power(x/C,B))           (4PL model)
# 
# or
# 
#     F(x|A,B,C,D,G) = D+(A-D)/Power(1+Power(x/C,B),G)    (5PL model)
# 
# Here:
#     * A, D - unconstrained
#     * B>=0 for 4PL, unconstrained for 5PL
#     * C>0
#     * G>0 (if present)
# 
# INPUT PARAMETERS:
#     X       -   array[N], stores X-values.
#                 MUST include only non-negative numbers  (but  may  include
#                 zero values). Can be unsorted.
#     Y       -   array[N], values to fit.
#     N       -   number of points. If N is less than  length  of  X/Y, only
#                 leading N elements are used.
#     CnstrLeft-  optional equality constraint for model value at the   left
#                 boundary (at X=0). Specify NAN (Not-a-Number)  if  you  do
#                 not need constraint on the model value at X=0 (in C++  you
#                 can pass alglib::fp_nan as parameter, in  C#  it  will  be
#                 Double.NaN).
#                 See  below,  section  "EQUALITY  CONSTRAINTS"   for   more
#                 information about constraints.
#     CnstrRight- optional equality constraint for model value at X=infinity.
#                 Specify NAN (Not-a-Number) if you do not  need  constraint
#                 on the model value (in C++  you can pass alglib::fp_nan as
#                 parameter, in  C# it will  be Double.NaN).
#                 See  below,  section  "EQUALITY  CONSTRAINTS"   for   more
#                 information about constraints.
#     Is4PL   -   whether 4PL or 5PL models are fitted
#     LambdaV -   regularization coefficient, LambdaV>=0.
#                 Set it to zero unless you know what you are doing.
#     EpsX    -   stopping condition (step size), EpsX>=0.
#                 Zero value means that small step is automatically chosen.
#                 See notes below for more information.
#     RsCnt   -   number of repeated restarts from  random  points.  4PL/5PL
#                 models are prone to problem of bad local extrema. Utilizing
#                 multiple random restarts allows  us  to  improve algorithm
#                 convergence.
#                 RsCnt>=0.
#                 Zero value means that function automatically choose  small
#                 amount of restarts (recommended).
# 
# OUTPUT PARAMETERS:
#     A, B, C, D- parameters of 4PL model
#     G       -   parameter of 5PL model; for Is4PL=True, G=1 is returned.
#     Rep     -   fitting report. This structure has many fields,  but  ONLY
#                 ONES LISTED BELOW ARE SET:
#                 * Rep.IterationsCount - number of iterations performed
#                 * Rep.RMSError - root-mean-square error
#                 * Rep.AvgError - average absolute error
#                 * Rep.AvgRelError - average relative error (calculated for
#                   non-zero Y-values)
#                 * Rep.MaxError - maximum absolute error
#                 * Rep.R2 - coefficient of determination,  R-squared.  This
#                   coefficient   is  calculated  as  R2=1-RSS/TSS  (in case
#                   of nonlinear  regression  there  are  multiple  ways  to
#                   define R2, each of them giving different results).
# 
# NOTE: after  you  obtained  coefficients,  you  can  evaluate  model  with
#       LogisticCalc5() function.
# 
# NOTE: step is automatically scaled according to scale of parameters  being
#       fitted before we compare its length with EpsX. Thus,  this  function
#       can be used to fit data with very small or very large values without
#       changing EpsX.
# 
# EQUALITY CONSTRAINTS ON PARAMETERS
# 
# 4PL/5PL solver supports equality constraints on model values at  the  left
# boundary (X=0) and right  boundary  (X=infinity).  These  constraints  are
# completely optional and you can specify both of them, only  one  -  or  no
# constraints at all.
# 
# Parameter  CnstrLeft  contains  left  constraint (or NAN for unconstrained
# fitting), and CnstrRight contains right  one.  For  4PL,  left  constraint
# ALWAYS corresponds to parameter A, and right one is ALWAYS  constraint  on
# D. That's because 4PL model is normalized in such way that B>=0.
# 
# For 5PL model things are different. Unlike  4PL  one,  5PL  model  is  NOT
# symmetric with respect to  change  in  sign  of  B. Thus, negative B's are
# possible, and left constraint may constrain parameter A (for positive B's)
# - or parameter D (for negative B's). Similarly changes  meaning  of  right
# constraint.
# 
# You do not have to decide what parameter to  constrain  -  algorithm  will
# automatically determine correct parameters as fitting progresses. However,
# question highlighted above is important when you interpret fitting results.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 14.02.2014 by Bochkanov Sergey
#

SYNTAX: a, b, c, d, g, rep = xalglib.logisticfit45x(x, y, n, cnstrleft, cnstrright, is4pl, lambdav, epsx, rscnt)

logisticfit4ec function

#
# This function fits four-parameter logistic (4PL) model  to  data  provided
# by user, with optional constraints on parameters A and D.  4PL  model  has
# following form:
# 
#     F(x|A,B,C,D) = D+(A-D)/(1+Power(x/C,B))
# 
# Here:
#     * A, D - with optional equality constraints
#     * B>=0
#     * C>0
# 
# IMPORTANT: output of this function is constrained in  such  way that  B>0.
#            Because 4PL model is symmetric with respect to B, there  is  no
#            need to explore  B<0.  Constraining  B  makes  algorithm easier
#            to stabilize and debug.
#            Users  who  for  some  reason  prefer to work with negative B's
#            should transform output themselves (swap A and D, replace B  by
#            -B).
# 
# 4PL fitting is implemented as follows:
# * we perform small number of restarts from random locations which helps to
#   solve problem of bad local extrema. Locations are only partially  random
#   - we use input data to determine good  initial  guess,  but  we  include
#   controlled amount of randomness.
# * we perform Levenberg-Marquardt fitting with very  tight  constraints  on
#   parameters B and C - it allows us to find good  initial  guess  for  the
#   second stage without risk of running into "flat spot".
# * second  Levenberg-Marquardt  round  is   performed   without   excessive
#   constraints. Results from the previous round are used as initial guess.
# * after fitting is done, we compare results with best values found so far,
#   rewrite "best solution" if needed, and move to next random location.
# 
# Overall algorithm is very stable and is not prone to  bad  local  extrema.
# Furthermore, it automatically scales when input data have  very  large  or
# very small range.
# 
# INPUT PARAMETERS:
#     X       -   array[N], stores X-values.
#                 MUST include only non-negative numbers  (but  may  include
#                 zero values). Can be unsorted.
#     Y       -   array[N], values to fit.
#     N       -   number of points. If N is less than  length  of  X/Y, only
#                 leading N elements are used.
#     CnstrLeft-  optional equality constraint for model value at the   left
#                 boundary (at X=0). Specify NAN (Not-a-Number)  if  you  do
#                 not need constraint on the model value at X=0 (in C++  you
#                 can pass alglib::fp_nan as parameter, in  C#  it  will  be
#                 Double.NaN).
#                 See  below,  section  "EQUALITY  CONSTRAINTS"   for   more
#                 information about constraints.
#     CnstrRight- optional equality constraint for model value at X=infinity.
#                 Specify NAN (Not-a-Number) if you do not  need  constraint
#                 on the model value (in C++  you can pass alglib::fp_nan as
#                 parameter, in  C# it will  be Double.NaN).
#                 See  below,  section  "EQUALITY  CONSTRAINTS"   for   more
#                 information about constraints.
# 
# OUTPUT PARAMETERS:
#     A, B, C, D- parameters of 4PL model
#     Rep     -   fitting report. This structure has many fields,  but  ONLY
#                 ONES LISTED BELOW ARE SET:
#                 * Rep.IterationsCount - number of iterations performed
#                 * Rep.RMSError - root-mean-square error
#                 * Rep.AvgError - average absolute error
#                 * Rep.AvgRelError - average relative error (calculated for
#                   non-zero Y-values)
#                 * Rep.MaxError - maximum absolute error
#                 * Rep.R2 - coefficient of determination,  R-squared.  This
#                   coefficient   is  calculated  as  R2=1-RSS/TSS  (in case
#                   of nonlinear  regression  there  are  multiple  ways  to
#                   define R2, each of them giving different results).
# 
# NOTE: after  you  obtained  coefficients,  you  can  evaluate  model  with
#       LogisticCalc4() function.
# 
# NOTE: if you need better control over fitting process than provided by this
#       function, you may use LogisticFit45X().
# 
# NOTE: step is automatically scaled according to scale of parameters  being
#       fitted before we compare its length with EpsX. Thus,  this  function
#       can be used to fit data with very small or very large values without
#       changing EpsX.
# 
# EQUALITY CONSTRAINTS ON PARAMETERS
# 
# 4PL/5PL solver supports equality constraints on model values at  the  left
# boundary (X=0) and right  boundary  (X=infinity).  These  constraints  are
# completely optional and you can specify both of them, only  one  -  or  no
# constraints at all.
# 
# Parameter  CnstrLeft  contains  left  constraint (or NAN for unconstrained
# fitting), and CnstrRight contains right  one.  For  4PL,  left  constraint
# ALWAYS corresponds to parameter A, and right one is ALWAYS  constraint  on
# D. That's because 4PL model is normalized in such way that B>=0.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 14.02.2014 by Bochkanov Sergey
#

SYNTAX: a, b, c, d, rep = xalglib.logisticfit4ec(x, y, n, cnstrleft, cnstrright)

logisticfit5 function

#
# This function fits five-parameter logistic (5PL) model  to  data  provided
# by user. 5PL model has following form:
# 
#     F(x|A,B,C,D,G) = D+(A-D)/Power(1+Power(x/C,B),G)
# 
# Here:
#     * A, D - unconstrained
#     * B - unconstrained
#     * C>0
#     * G>0
# 
# IMPORTANT: unlike in  4PL  fitting,  output  of  this  function   is   NOT
#            constrained in  such  way that B is guaranteed to be  positive.
#            Furthermore,  unlike  4PL,  5PL  model  is  NOT  symmetric with
#            respect to B, so you can NOT transform model to equivalent one,
#            with B having desired sign (>0 or <0).
# 
# 5PL fitting is implemented as follows:
# * we perform small number of restarts from random locations which helps to
#   solve problem of bad local extrema. Locations are only partially  random
#   - we use input data to determine good  initial  guess,  but  we  include
#   controlled amount of randomness.
# * we perform Levenberg-Marquardt fitting with very  tight  constraints  on
#   parameters B and C - it allows us to find good  initial  guess  for  the
#   second stage without risk of running into "flat spot".  Parameter  G  is
#   fixed at G=1.
# * second  Levenberg-Marquardt  round  is   performed   without   excessive
#   constraints on B and C, but with G still equal to 1.  Results  from  the
#   previous round are used as initial guess.
# * third Levenberg-Marquardt round relaxes constraints on G  and  tries  two
#   different models - one with B>0 and one with B<0.
# * after fitting is done, we compare results with best values found so far,
#   rewrite "best solution" if needed, and move to next random location.
# 
# Overall algorithm is very stable and is not prone to  bad  local  extrema.
# Furthermore, it automatically scales when input data have  very  large  or
# very small range.
# 
# INPUT PARAMETERS:
#     X       -   array[N], stores X-values.
#                 MUST include only non-negative numbers  (but  may  include
#                 zero values). Can be unsorted.
#     Y       -   array[N], values to fit.
#     N       -   number of points. If N is less than  length  of  X/Y, only
#                 leading N elements are used.
# 
# OUTPUT PARAMETERS:
#     A,B,C,D,G-  parameters of 5PL model
#     Rep     -   fitting report. This structure has many fields,  but  ONLY
#                 ONES LISTED BELOW ARE SET:
#                 * Rep.IterationsCount - number of iterations performed
#                 * Rep.RMSError - root-mean-square error
#                 * Rep.AvgError - average absolute error
#                 * Rep.AvgRelError - average relative error (calculated for
#                   non-zero Y-values)
#                 * Rep.MaxError - maximum absolute error
#                 * Rep.R2 - coefficient of determination,  R-squared.  This
#                   coefficient   is  calculated  as  R2=1-RSS/TSS  (in case
#                   of nonlinear  regression  there  are  multiple  ways  to
#                   define R2, each of them giving different results).
# 
# NOTE: after  you  obtained  coefficients,  you  can  evaluate  model  with
#       LogisticCalc5() function.
# 
# NOTE: if you need better control over fitting process than provided by this
#       function, you may use LogisticFit45X().
# 
# NOTE: step is automatically scaled according to scale of parameters  being
#       fitted before we compare its length with EpsX. Thus,  this  function
#       can be used to fit data with very small or very large values without
#       changing EpsX.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 14.02.2014 by Bochkanov Sergey
#

SYNTAX: a, b, c, d, g, rep = xalglib.logisticfit5(x, y, n)

Examples:   [1]  

logisticfit5ec function

#
# This function fits five-parameter logistic (5PL) model  to  data  provided
# by user, subject to optional equality constraints on parameters A  and  D.
# 5PL model has following form:
# 
#     F(x|A,B,C,D,G) = D+(A-D)/Power(1+Power(x/C,B),G)
# 
# Here:
#     * A, D - with optional equality constraints
#     * B - unconstrained
#     * C>0
#     * G>0
# 
# IMPORTANT: unlike in  4PL  fitting,  output  of  this  function   is   NOT
#            constrained in  such  way that B is guaranteed to be  positive.
#            Furthermore,  unlike  4PL,  5PL  model  is  NOT  symmetric with
#            respect to B, so you can NOT transform model to equivalent one,
#            with B having desired sign (>0 or <0).
# 
# 5PL fitting is implemented as follows:
# * we perform small number of restarts from random locations which helps to
#   solve problem of bad local extrema. Locations are only partially  random
#   - we use input data to determine good  initial  guess,  but  we  include
#   controlled amount of randomness.
# * we perform Levenberg-Marquardt fitting with very  tight  constraints  on
#   parameters B and C - it allows us to find good  initial  guess  for  the
#   second stage without risk of running into "flat spot".  Parameter  G  is
#   fixed at G=1.
# * second  Levenberg-Marquardt  round  is   performed   without   excessive
#   constraints on B and C, but with G still equal to 1.  Results  from  the
#   previous round are used as initial guess.
# * third Levenberg-Marquardt round relaxes constraints on G  and  tries  two
#   different models - one with B>0 and one with B<0.
# * after fitting is done, we compare results with best values found so far,
#   rewrite "best solution" if needed, and move to next random location.
# 
# Overall algorithm is very stable and is not prone to  bad  local  extrema.
# Furthermore, it automatically scales when input data have  very  large  or
# very small range.
# 
# INPUT PARAMETERS:
#     X       -   array[N], stores X-values.
#                 MUST include only non-negative numbers  (but  may  include
#                 zero values). Can be unsorted.
#     Y       -   array[N], values to fit.
#     N       -   number of points. If N is less than  length  of  X/Y, only
#                 leading N elements are used.
#     CnstrLeft-  optional equality constraint for model value at the   left
#                 boundary (at X=0). Specify NAN (Not-a-Number)  if  you  do
#                 not need constraint on the model value at X=0 (in C++  you
#                 can pass alglib::fp_nan as parameter, in  C#  it  will  be
#                 Double.NaN).
#                 See  below,  section  "EQUALITY  CONSTRAINTS"   for   more
#                 information about constraints.
#     CnstrRight- optional equality constraint for model value at X=infinity.
#                 Specify NAN (Not-a-Number) if you do not  need  constraint
#                 on the model value (in C++  you can pass alglib::fp_nan as
#                 parameter, in  C# it will  be Double.NaN).
#                 See  below,  section  "EQUALITY  CONSTRAINTS"   for   more
#                 information about constraints.
# 
# OUTPUT PARAMETERS:
#     A,B,C,D,G-  parameters of 5PL model
#     Rep     -   fitting report. This structure has many fields,  but  ONLY
#                 ONES LISTED BELOW ARE SET:
#                 * Rep.IterationsCount - number of iterations performed
#                 * Rep.RMSError - root-mean-square error
#                 * Rep.AvgError - average absolute error
#                 * Rep.AvgRelError - average relative error (calculated for
#                   non-zero Y-values)
#                 * Rep.MaxError - maximum absolute error
#                 * Rep.R2 - coefficient of determination,  R-squared.  This
#                   coefficient   is  calculated  as  R2=1-RSS/TSS  (in case
#                   of nonlinear  regression  there  are  multiple  ways  to
#                   define R2, each of them giving different results).
# 
# NOTE: after  you  obtained  coefficients,  you  can  evaluate  model  with
#       LogisticCalc5() function.
# 
# NOTE: if you need better control over fitting process than provided by this
#       function, you may use LogisticFit45X().
# 
# NOTE: step is automatically scaled according to scale of parameters  being
#       fitted before we compare its length with EpsX. Thus,  this  function
#       can be used to fit data with very small or very large values without
#       changing EpsX.
# 
# EQUALITY CONSTRAINTS ON PARAMETERS
# 
# 5PL solver supports equality constraints on model  values  at   the   left
# boundary (X=0) and right  boundary  (X=infinity).  These  constraints  are
# completely optional and you can specify both of them, only  one  -  or  no
# constraints at all.
# 
# Parameter  CnstrLeft  contains  left  constraint (or NAN for unconstrained
# fitting), and CnstrRight contains right  one.
# 
# Unlike 4PL one, 5PL model is NOT symmetric with respect to  change in sign
# of B. Thus, negative B's are possible, and left constraint  may  constrain
# parameter A (for positive B's)  -  or  parameter  D  (for  negative  B's).
# Similarly changes meaning of right constraint.
# 
# You do not have to decide what parameter to  constrain  -  algorithm  will
# automatically determine correct parameters as fitting progresses. However,
# question highlighted above is important when you interpret fitting results.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 14.02.2014 by Bochkanov Sergey
#

SYNTAX: a, b, c, d, g, rep = xalglib.logisticfit5ec(x, y, n, cnstrleft, cnstrright)

lsfitcreatef function

#
# Nonlinear least squares fitting using function values only.
# 
# Combination of numerical differentiation and secant updates is used to
# obtain function Jacobian.
# 
# Nonlinear task min(F(c)) is solved, where
# 
#     F(c) = (f(c,x[0])-y[0])^2 + ... + (f(c,x[n-1])-y[n-1])^2,
# 
#     * N is a number of points,
#     * M is a dimension of a space points belong to,
#     * K is a dimension of a space of parameters being fitted,
#     * w is an N-dimensional vector of weight coefficients,
#     * x is a set of N points, each of them is an M-dimensional vector,
#     * c is a K-dimensional vector of parameters being fitted
# 
# This subroutine uses only f(c,x[i]).
# 
# INPUT PARAMETERS:
#     X       -   array[0..N-1,0..M-1], points (one row = one point)
#     Y       -   array[0..N-1], function values.
#     C       -   array[0..K-1], initial approximation to the solution,
#     N       -   number of points, N>1
#     M       -   dimension of space
#     K       -   number of parameters being fitted
#     DiffStep-   numerical differentiation step;
#                 should not be very small or large;
#                 large = loss of accuracy
#                 small = growth of round-off errors
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 18.10.2008 by Bochkanov Sergey
#

SYNTAX: state = xalglib.lsfitcreatef(x, y, c, n, m, k, diffstep)
SYNTAX: state = xalglib.lsfitcreatef(x, y, c, diffstep)

Examples:   [1]  [2]  [3]  

lsfitcreatefg function

#
# Nonlinear least squares fitting using gradient only, without individual
# weights.
# 
# Nonlinear task min(F(c)) is solved, where
# 
#     F(c) = ((f(c,x[0])-y[0]))^2 + ... + ((f(c,x[n-1])-y[n-1]))^2,
# 
#     * N is a number of points,
#     * M is a dimension of a space points belong to,
#     * K is a dimension of a space of parameters being fitted,
#     * x is a set of N points, each of them is an M-dimensional vector,
#     * c is a K-dimensional vector of parameters being fitted
# 
# This subroutine uses only f(c,x[i]) and its gradient.
# 
# INPUT PARAMETERS:
#     X       -   array[0..N-1,0..M-1], points (one row = one point)
#     Y       -   array[0..N-1], function values.
#     C       -   array[0..K-1], initial approximation to the solution,
#     N       -   number of points, N>1
#     M       -   dimension of space
#     K       -   number of parameters being fitted
#     CheapFG -   boolean flag, which is:
#                 * True  if both function and gradient calculation complexity
#                         are less than O(M^2).  An improved  algorithm  can
#                         be  used  which corresponds  to  FGJ  scheme  from
#                         MINLM unit.
#                 * False otherwise.
#                         Standard Jacibian-bases  Levenberg-Marquardt  algo
#                         will be used (FJ scheme).
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.lsfitcreatefg(x, y, c, n, m, k, cheapfg)
SYNTAX: state = xalglib.lsfitcreatefg(x, y, c, cheapfg)

Examples:   [1]  

lsfitcreatefgh function

#
# Nonlinear least squares fitting using gradient/Hessian, without individial
# weights.
# 
# Nonlinear task min(F(c)) is solved, where
# 
#     F(c) = ((f(c,x[0])-y[0]))^2 + ... + ((f(c,x[n-1])-y[n-1]))^2,
# 
#     * N is a number of points,
#     * M is a dimension of a space points belong to,
#     * K is a dimension of a space of parameters being fitted,
#     * x is a set of N points, each of them is an M-dimensional vector,
#     * c is a K-dimensional vector of parameters being fitted
# 
# This subroutine uses f(c,x[i]), its gradient and its Hessian.
# 
# INPUT PARAMETERS:
#     X       -   array[0..N-1,0..M-1], points (one row = one point)
#     Y       -   array[0..N-1], function values.
#     C       -   array[0..K-1], initial approximation to the solution,
#     N       -   number of points, N>1
#     M       -   dimension of space
#     K       -   number of parameters being fitted
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.lsfitcreatefgh(x, y, c, n, m, k)
SYNTAX: state = xalglib.lsfitcreatefgh(x, y, c)

Examples:   [1]  

lsfitcreatewf function

#
# Weighted nonlinear least squares fitting using function values only.
# 
# Combination of numerical differentiation and secant updates is used to
# obtain function Jacobian.
# 
# Nonlinear task min(F(c)) is solved, where
# 
#     F(c) = (w[0]*(f(c,x[0])-y[0]))^2 + ... + (w[n-1]*(f(c,x[n-1])-y[n-1]))^2,
# 
#     * N is a number of points,
#     * M is a dimension of a space points belong to,
#     * K is a dimension of a space of parameters being fitted,
#     * w is an N-dimensional vector of weight coefficients,
#     * x is a set of N points, each of them is an M-dimensional vector,
#     * c is a K-dimensional vector of parameters being fitted
# 
# This subroutine uses only f(c,x[i]).
# 
# INPUT PARAMETERS:
#     X       -   array[0..N-1,0..M-1], points (one row = one point)
#     Y       -   array[0..N-1], function values.
#     W       -   weights, array[0..N-1]
#     C       -   array[0..K-1], initial approximation to the solution,
#     N       -   number of points, N>1
#     M       -   dimension of space
#     K       -   number of parameters being fitted
#     DiffStep-   numerical differentiation step;
#                 should not be very small or large;
#                 large = loss of accuracy
#                 small = growth of round-off errors
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 18.10.2008 by Bochkanov Sergey
#

SYNTAX: state = xalglib.lsfitcreatewf(x, y, w, c, n, m, k, diffstep)
SYNTAX: state = xalglib.lsfitcreatewf(x, y, w, c, diffstep)

Examples:   [1]  [2]  

lsfitcreatewfg function

#
# Weighted nonlinear least squares fitting using gradient only.
# 
# Nonlinear task min(F(c)) is solved, where
# 
#     F(c) = (w[0]*(f(c,x[0])-y[0]))^2 + ... + (w[n-1]*(f(c,x[n-1])-y[n-1]))^2,
# 
#     * N is a number of points,
#     * M is a dimension of a space points belong to,
#     * K is a dimension of a space of parameters being fitted,
#     * w is an N-dimensional vector of weight coefficients,
#     * x is a set of N points, each of them is an M-dimensional vector,
#     * c is a K-dimensional vector of parameters being fitted
# 
# This subroutine uses only f(c,x[i]) and its gradient.
# 
# INPUT PARAMETERS:
#     X       -   array[0..N-1,0..M-1], points (one row = one point)
#     Y       -   array[0..N-1], function values.
#     W       -   weights, array[0..N-1]
#     C       -   array[0..K-1], initial approximation to the solution,
#     N       -   number of points, N>1
#     M       -   dimension of space
#     K       -   number of parameters being fitted
#     CheapFG -   boolean flag, which is:
#                 * True  if both function and gradient calculation complexity
#                         are less than O(M^2).  An improved  algorithm  can
#                         be  used  which corresponds  to  FGJ  scheme  from
#                         MINLM unit.
#                 * False otherwise.
#                         Standard Jacibian-bases  Levenberg-Marquardt  algo
#                         will be used (FJ scheme).
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# See also:
#     LSFitResults
#     LSFitCreateFG (fitting without weights)
#     LSFitCreateWFGH (fitting using Hessian)
#     LSFitCreateFGH (fitting using Hessian, without weights)
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.lsfitcreatewfg(x, y, w, c, n, m, k, cheapfg)
SYNTAX: state = xalglib.lsfitcreatewfg(x, y, w, c, cheapfg)

Examples:   [1]  

lsfitcreatewfgh function

#
# Weighted nonlinear least squares fitting using gradient/Hessian.
# 
# Nonlinear task min(F(c)) is solved, where
# 
#     F(c) = (w[0]*(f(c,x[0])-y[0]))^2 + ... + (w[n-1]*(f(c,x[n-1])-y[n-1]))^2,
# 
#     * N is a number of points,
#     * M is a dimension of a space points belong to,
#     * K is a dimension of a space of parameters being fitted,
#     * w is an N-dimensional vector of weight coefficients,
#     * x is a set of N points, each of them is an M-dimensional vector,
#     * c is a K-dimensional vector of parameters being fitted
# 
# This subroutine uses f(c,x[i]), its gradient and its Hessian.
# 
# INPUT PARAMETERS:
#     X       -   array[0..N-1,0..M-1], points (one row = one point)
#     Y       -   array[0..N-1], function values.
#     W       -   weights, array[0..N-1]
#     C       -   array[0..K-1], initial approximation to the solution,
#     N       -   number of points, N>1
#     M       -   dimension of space
#     K       -   number of parameters being fitted
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.lsfitcreatewfgh(x, y, w, c, n, m, k)
SYNTAX: state = xalglib.lsfitcreatewfgh(x, y, w, c)

Examples:   [1]  

lsfitfit function

#
# This family of functions is used to launcn iterations of nonlinear fitter
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     func    -   callback which calculates function (or merit function)
#                 value func at given point x
#     grad    -   callback which calculates function (or merit function)
#                 value func and gradient grad at given point x
#     hess    -   callback which calculates function (or merit function)
#                 value func, gradient grad and Hessian hess at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# NOTES:
# 
# 1. this algorithm is somewhat unusual because it works with  parameterized
#    function f(C,X), where X is a function argument (we  have  many  points
#    which are characterized by different  argument  values),  and  C  is  a
#    parameter to fit.
# 
#    For example, if we want to do linear fit by f(c0,c1,x) = c0*x+c1,  then
#    x will be argument, and {c0,c1} will be parameters.
# 
#    It is important to understand that this algorithm finds minimum in  the
#    space of function PARAMETERS (not arguments), so it  needs  derivatives
#    of f() with respect to C, not X.
# 
#    In the example above it will need f=c0*x+c1 and {df/dc0,df/dc1} = {x,1}
#    instead of {df/dx} = {c0}.
# 
# 2. Callback functions accept C as the first parameter, and X as the second
# 
# 3. If  state  was  created  with  LSFitCreateFG(),  algorithm  needs  just
#    function   and   its   gradient,   but   if   state   was  created with
#    LSFitCreateFGH(), algorithm will need function, gradient and Hessian.
# 
#    According  to  the  said  above,  there  ase  several  versions of this
#    function, which accept different sets of callbacks.
# 
#    This flexibility opens way to subtle errors - you may create state with
#    LSFitCreateFGH() (optimization using Hessian), but call function  which
#    does not accept Hessian. So when algorithm will request Hessian,  there
#    will be no callback to call. In this case exception will be thrown.
# 
#    Be careful to avoid such errors because there is no way to find them at
#    compile time - you can see them at runtime only.
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitfit_f(state, func, rep = None, param = None)
SYNTAX: xalglib.lsfitfit_fg(state, func, grad, rep = None, param = None)
SYNTAX: xalglib.lsfitfit_fgh(state, func, grad, hess, rep = None, param = None)

Examples:   [1]  [2]  [3]  [4]  [5]  

lsfitlinear function

#
# Linear least squares fitting.
# 
# QR decomposition is used to reduce task to MxM, then triangular solver  or
# SVD-based solver is used depending on condition number of the  system.  It
# allows to maximize speed and retain decent accuracy.
# 
# IMPORTANT: if you want to perform  polynomial  fitting,  it  may  be  more
#            convenient to use PolynomialFit() function. This function gives
#            best  results  on  polynomial  problems  and  solves  numerical
#            stability  issues  which  arise  when   you   fit   high-degree
#            polynomials to your data.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     Y       -   array[0..N-1] Function values in  N  points.
#     FMatrix -   a table of basis functions values, array[0..N-1, 0..M-1].
#                 FMatrix[I, J] - value of J-th basis function in I-th point.
#     N       -   number of points used. N>=1.
#     M       -   number of basis functions, M>=1.
# 
# OUTPUT PARAMETERS:
#     Info    -   error code:
#                 * -4    internal SVD decomposition subroutine failed (very
#                         rare and for degenerate systems only)
#                 *  1    task is solved
#     C       -   decomposition coefficients, array[0..M-1]
#     Rep     -   fitting report. Following fields are set:
#                 * Rep.TaskRCond     reciprocal of condition number
#                 * R2                non-adjusted coefficient of determination
#                                     (non-weighted)
#                 * RMSError          rms error on the (X,Y).
#                 * AvgError          average error on the (X,Y).
#                 * AvgRelError       average relative error on the non-zero Y
#                 * MaxError          maximum error
#                                     NON-WEIGHTED ERRORS ARE CALCULATED
# 
# ERRORS IN PARAMETERS
# 
# This  solver  also  calculates different kinds of errors in parameters and
# fills corresponding fields of report:
# * Rep.CovPar        covariance matrix for parameters, array[K,K].
# * Rep.ErrPar        errors in parameters, array[K],
#                     errpar = sqrt(diag(CovPar))
# * Rep.ErrCurve      vector of fit errors - standard deviations of empirical
#                     best-fit curve from "ideal" best-fit curve built  with
#                     infinite number of samples, array[N].
#                     errcurve = sqrt(diag(F*CovPar*F')),
#                     where F is functions matrix.
# * Rep.Noise         vector of per-point estimates of noise, array[N]
# 
# NOTE:       noise in the data is estimated as follows:
#             * for fitting without user-supplied  weights  all  points  are
#               assumed to have same level of noise, which is estimated from
#               the data
#             * for fitting with user-supplied weights we assume that  noise
#               level in I-th point is inversely proportional to Ith weight.
#               Coefficient of proportionality is estimated from the data.
# 
# NOTE:       we apply small amount of regularization when we invert squared
#             Jacobian and calculate covariance matrix. It  guarantees  that
#             algorithm won't divide by zero  during  inversion,  but  skews
#             error estimates a bit (fractional error is about 10^-9).
# 
#             However, we believe that this difference is insignificant  for
#             all practical purposes except for the situation when you  want
#             to compare ALGLIB results with "reference"  implementation  up
#             to the last significant digit.
# 
# NOTE:       covariance matrix is estimated using  correction  for  degrees
#             of freedom (covariances are divided by N-M instead of dividing
#             by N).
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: info, c, rep = xalglib.lsfitlinear(y, fmatrix, n, m)
SYNTAX: info, c, rep = xalglib.lsfitlinear(y, fmatrix)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinear(y, fmatrix, n, m)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinear(y, fmatrix)

Examples:   [1]  

lsfitlinearc function

#
# Constained linear least squares fitting.
# 
# This  is  variation  of LSFitLinear(),  which searchs for min|A*x=b| given
# that  K  additional  constaints  C*x=bc are satisfied. It reduces original
# task to modified one: min|B*y-d| WITHOUT constraints,  then  LSFitLinear()
# is called.
# 
# IMPORTANT: if you want to perform  polynomial  fitting,  it  may  be  more
#            convenient to use PolynomialFit() function. This function gives
#            best  results  on  polynomial  problems  and  solves  numerical
#            stability  issues  which  arise  when   you   fit   high-degree
#            polynomials to your data.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     Y       -   array[0..N-1] Function values in  N  points.
#     FMatrix -   a table of basis functions values, array[0..N-1, 0..M-1].
#                 FMatrix[I,J] - value of J-th basis function in I-th point.
#     CMatrix -   a table of constaints, array[0..K-1,0..M].
#                 I-th row of CMatrix corresponds to I-th linear constraint:
#                 CMatrix[I,0]*C[0] + ... + CMatrix[I,M-1]*C[M-1] = CMatrix[I,M]
#     N       -   number of points used. N>=1.
#     M       -   number of basis functions, M>=1.
#     K       -   number of constraints, 0 <= K < M
#                 K=0 corresponds to absence of constraints.
# 
# OUTPUT PARAMETERS:
#     Info    -   error code:
#                 * -4    internal SVD decomposition subroutine failed (very
#                         rare and for degenerate systems only)
#                 * -3    either   too   many  constraints  (M   or   more),
#                         degenerate  constraints   (some   constraints  are
#                         repetead twice) or inconsistent  constraints  were
#                         specified.
#                 *  1    task is solved
#     C       -   decomposition coefficients, array[0..M-1]
#     Rep     -   fitting report. Following fields are set:
#                 * R2                non-adjusted coefficient of determination
#                                     (non-weighted)
#                 * RMSError          rms error on the (X,Y).
#                 * AvgError          average error on the (X,Y).
#                 * AvgRelError       average relative error on the non-zero Y
#                 * MaxError          maximum error
#                                     NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroitine doesn't calculate task's condition number for K<>0.
# 
# ERRORS IN PARAMETERS
# 
# This  solver  also  calculates different kinds of errors in parameters and
# fills corresponding fields of report:
# * Rep.CovPar        covariance matrix for parameters, array[K,K].
# * Rep.ErrPar        errors in parameters, array[K],
#                     errpar = sqrt(diag(CovPar))
# * Rep.ErrCurve      vector of fit errors - standard deviations of empirical
#                     best-fit curve from "ideal" best-fit curve built  with
#                     infinite number of samples, array[N].
#                     errcurve = sqrt(diag(F*CovPar*F')),
#                     where F is functions matrix.
# * Rep.Noise         vector of per-point estimates of noise, array[N]
# 
# IMPORTANT:  errors  in  parameters  are  calculated  without  taking  into
#             account boundary/linear constraints! Presence  of  constraints
#             changes distribution of errors, but there is no  easy  way  to
#             account for constraints when you calculate covariance matrix.
# 
# NOTE:       noise in the data is estimated as follows:
#             * for fitting without user-supplied  weights  all  points  are
#               assumed to have same level of noise, which is estimated from
#               the data
#             * for fitting with user-supplied weights we assume that  noise
#               level in I-th point is inversely proportional to Ith weight.
#               Coefficient of proportionality is estimated from the data.
# 
# NOTE:       we apply small amount of regularization when we invert squared
#             Jacobian and calculate covariance matrix. It  guarantees  that
#             algorithm won't divide by zero  during  inversion,  but  skews
#             error estimates a bit (fractional error is about 10^-9).
# 
#             However, we believe that this difference is insignificant  for
#             all practical purposes except for the situation when you  want
#             to compare ALGLIB results with "reference"  implementation  up
#             to the last significant digit.
# 
# NOTE:       covariance matrix is estimated using  correction  for  degrees
#             of freedom (covariances are divided by N-M instead of dividing
#             by N).
# 
#   -- ALGLIB --
#      Copyright 07.09.2009 by Bochkanov Sergey
#

SYNTAX: info, c, rep = xalglib.lsfitlinearc(y, fmatrix, cmatrix, n, m, k)
SYNTAX: info, c, rep = xalglib.lsfitlinearc(y, fmatrix, cmatrix)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinearc(y, fmatrix, cmatrix, n, m, k)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinearc(y, fmatrix, cmatrix)

Examples:   [1]  

lsfitlinearw function

#
# Weighted linear least squares fitting.
# 
# QR decomposition is used to reduce task to MxM, then triangular solver  or
# SVD-based solver is used depending on condition number of the  system.  It
# allows to maximize speed and retain decent accuracy.
# 
# IMPORTANT: if you want to perform  polynomial  fitting,  it  may  be  more
#            convenient to use PolynomialFit() function. This function gives
#            best  results  on  polynomial  problems  and  solves  numerical
#            stability  issues  which  arise  when   you   fit   high-degree
#            polynomials to your data.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     Y       -   array[0..N-1] Function values in  N  points.
#     W       -   array[0..N-1]  Weights  corresponding to function  values.
#                 Each summand in square  sum  of  approximation  deviations
#                 from  given  values  is  multiplied  by  the   square   of
#                 corresponding weight.
#     FMatrix -   a table of basis functions values, array[0..N-1, 0..M-1].
#                 FMatrix[I, J] - value of J-th basis function in I-th point.
#     N       -   number of points used. N>=1.
#     M       -   number of basis functions, M>=1.
# 
# OUTPUT PARAMETERS:
#     Info    -   error code:
#                 * -4    internal SVD decomposition subroutine failed (very
#                         rare and for degenerate systems only)
#                 * -1    incorrect N/M were specified
#                 *  1    task is solved
#     C       -   decomposition coefficients, array[0..M-1]
#     Rep     -   fitting report. Following fields are set:
#                 * Rep.TaskRCond     reciprocal of condition number
#                 * R2                non-adjusted coefficient of determination
#                                     (non-weighted)
#                 * RMSError          rms error on the (X,Y).
#                 * AvgError          average error on the (X,Y).
#                 * AvgRelError       average relative error on the non-zero Y
#                 * MaxError          maximum error
#                                     NON-WEIGHTED ERRORS ARE CALCULATED
# 
# ERRORS IN PARAMETERS
# 
# This  solver  also  calculates different kinds of errors in parameters and
# fills corresponding fields of report:
# * Rep.CovPar        covariance matrix for parameters, array[K,K].
# * Rep.ErrPar        errors in parameters, array[K],
#                     errpar = sqrt(diag(CovPar))
# * Rep.ErrCurve      vector of fit errors - standard deviations of empirical
#                     best-fit curve from "ideal" best-fit curve built  with
#                     infinite number of samples, array[N].
#                     errcurve = sqrt(diag(F*CovPar*F')),
#                     where F is functions matrix.
# * Rep.Noise         vector of per-point estimates of noise, array[N]
# 
# NOTE:       noise in the data is estimated as follows:
#             * for fitting without user-supplied  weights  all  points  are
#               assumed to have same level of noise, which is estimated from
#               the data
#             * for fitting with user-supplied weights we assume that  noise
#               level in I-th point is inversely proportional to Ith weight.
#               Coefficient of proportionality is estimated from the data.
# 
# NOTE:       we apply small amount of regularization when we invert squared
#             Jacobian and calculate covariance matrix. It  guarantees  that
#             algorithm won't divide by zero  during  inversion,  but  skews
#             error estimates a bit (fractional error is about 10^-9).
# 
#             However, we believe that this difference is insignificant  for
#             all practical purposes except for the situation when you  want
#             to compare ALGLIB results with "reference"  implementation  up
#             to the last significant digit.
# 
# NOTE:       covariance matrix is estimated using  correction  for  degrees
#             of freedom (covariances are divided by N-M instead of dividing
#             by N).
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: info, c, rep = xalglib.lsfitlinearw(y, w, fmatrix, n, m)
SYNTAX: info, c, rep = xalglib.lsfitlinearw(y, w, fmatrix)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinearw(y, w, fmatrix, n, m)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinearw(y, w, fmatrix)

Examples:   [1]  

lsfitlinearwc function

#
# Weighted constained linear least squares fitting.
# 
# This  is  variation  of LSFitLinearW(), which searchs for min|A*x=b| given
# that  K  additional  constaints  C*x=bc are satisfied. It reduces original
# task to modified one: min|B*y-d| WITHOUT constraints,  then LSFitLinearW()
# is called.
# 
# IMPORTANT: if you want to perform  polynomial  fitting,  it  may  be  more
#            convenient to use PolynomialFit() function. This function gives
#            best  results  on  polynomial  problems  and  solves  numerical
#            stability  issues  which  arise  when   you   fit   high-degree
#            polynomials to your data.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     Y       -   array[0..N-1] Function values in  N  points.
#     W       -   array[0..N-1]  Weights  corresponding to function  values.
#                 Each summand in square  sum  of  approximation  deviations
#                 from  given  values  is  multiplied  by  the   square   of
#                 corresponding weight.
#     FMatrix -   a table of basis functions values, array[0..N-1, 0..M-1].
#                 FMatrix[I,J] - value of J-th basis function in I-th point.
#     CMatrix -   a table of constaints, array[0..K-1,0..M].
#                 I-th row of CMatrix corresponds to I-th linear constraint:
#                 CMatrix[I,0]*C[0] + ... + CMatrix[I,M-1]*C[M-1] = CMatrix[I,M]
#     N       -   number of points used. N>=1.
#     M       -   number of basis functions, M>=1.
#     K       -   number of constraints, 0 <= K < M
#                 K=0 corresponds to absence of constraints.
# 
# OUTPUT PARAMETERS:
#     Info    -   error code:
#                 * -4    internal SVD decomposition subroutine failed (very
#                         rare and for degenerate systems only)
#                 * -3    either   too   many  constraints  (M   or   more),
#                         degenerate  constraints   (some   constraints  are
#                         repetead twice) or inconsistent  constraints  were
#                         specified.
#                 *  1    task is solved
#     C       -   decomposition coefficients, array[0..M-1]
#     Rep     -   fitting report. Following fields are set:
#                 * R2                non-adjusted coefficient of determination
#                                     (non-weighted)
#                 * RMSError          rms error on the (X,Y).
#                 * AvgError          average error on the (X,Y).
#                 * AvgRelError       average relative error on the non-zero Y
#                 * MaxError          maximum error
#                                     NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroitine doesn't calculate task's condition number for K<>0.
# 
# ERRORS IN PARAMETERS
# 
# This  solver  also  calculates different kinds of errors in parameters and
# fills corresponding fields of report:
# * Rep.CovPar        covariance matrix for parameters, array[K,K].
# * Rep.ErrPar        errors in parameters, array[K],
#                     errpar = sqrt(diag(CovPar))
# * Rep.ErrCurve      vector of fit errors - standard deviations of empirical
#                     best-fit curve from "ideal" best-fit curve built  with
#                     infinite number of samples, array[N].
#                     errcurve = sqrt(diag(F*CovPar*F')),
#                     where F is functions matrix.
# * Rep.Noise         vector of per-point estimates of noise, array[N]
# 
# IMPORTANT:  errors  in  parameters  are  calculated  without  taking  into
#             account boundary/linear constraints! Presence  of  constraints
#             changes distribution of errors, but there is no  easy  way  to
#             account for constraints when you calculate covariance matrix.
# 
# NOTE:       noise in the data is estimated as follows:
#             * for fitting without user-supplied  weights  all  points  are
#               assumed to have same level of noise, which is estimated from
#               the data
#             * for fitting with user-supplied weights we assume that  noise
#               level in I-th point is inversely proportional to Ith weight.
#               Coefficient of proportionality is estimated from the data.
# 
# NOTE:       we apply small amount of regularization when we invert squared
#             Jacobian and calculate covariance matrix. It  guarantees  that
#             algorithm won't divide by zero  during  inversion,  but  skews
#             error estimates a bit (fractional error is about 10^-9).
# 
#             However, we believe that this difference is insignificant  for
#             all practical purposes except for the situation when you  want
#             to compare ALGLIB results with "reference"  implementation  up
#             to the last significant digit.
# 
# NOTE:       covariance matrix is estimated using  correction  for  degrees
#             of freedom (covariances are divided by N-M instead of dividing
#             by N).
# 
#   -- ALGLIB --
#      Copyright 07.09.2009 by Bochkanov Sergey
#

SYNTAX: info, c, rep = xalglib.lsfitlinearwc(y, w, fmatrix, cmatrix, n, m, k)
SYNTAX: info, c, rep = xalglib.lsfitlinearwc(y, w, fmatrix, cmatrix)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinearwc(y, w, fmatrix, cmatrix, n, m, k)
SYNTAX: info, c, rep = xalglib.smp_lsfitlinearwc(y, w, fmatrix, cmatrix)

Examples:   [1]  

lsfitresults function

#
# Nonlinear least squares fitting results.
# 
# Called after return from LSFitFit().
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     Info    -   completion code:
#                     * -7    gradient verification failed.
#                             See LSFitSetGradientCheck() for more information.
#                     *  2    relative step is no more than EpsX.
#                     *  5    MaxIts steps was taken
#                     *  7    stopping conditions are too stringent,
#                             further improvement is impossible
#     C       -   array[0..K-1], solution
#     Rep     -   optimization report. On success following fields are set:
#                 * R2                non-adjusted coefficient of determination
#                                     (non-weighted)
#                 * RMSError          rms error on the (X,Y).
#                 * AvgError          average error on the (X,Y).
#                 * AvgRelError       average relative error on the non-zero Y
#                 * MaxError          maximum error
#                                     NON-WEIGHTED ERRORS ARE CALCULATED
#                 * WRMSError         weighted rms error on the (X,Y).
# 
# ERRORS IN PARAMETERS
# 
# This  solver  also  calculates different kinds of errors in parameters and
# fills corresponding fields of report:
# * Rep.CovPar        covariance matrix for parameters, array[K,K].
# * Rep.ErrPar        errors in parameters, array[K],
#                     errpar = sqrt(diag(CovPar))
# * Rep.ErrCurve      vector of fit errors - standard deviations of empirical
#                     best-fit curve from "ideal" best-fit curve built  with
#                     infinite number of samples, array[N].
#                     errcurve = sqrt(diag(J*CovPar*J')),
#                     where J is Jacobian matrix.
# * Rep.Noise         vector of per-point estimates of noise, array[N]
# 
# IMPORTANT:  errors  in  parameters  are  calculated  without  taking  into
#             account boundary/linear constraints! Presence  of  constraints
#             changes distribution of errors, but there is no  easy  way  to
#             account for constraints when you calculate covariance matrix.
# 
# NOTE:       noise in the data is estimated as follows:
#             * for fitting without user-supplied  weights  all  points  are
#               assumed to have same level of noise, which is estimated from
#               the data
#             * for fitting with user-supplied weights we assume that  noise
#               level in I-th point is inversely proportional to Ith weight.
#               Coefficient of proportionality is estimated from the data.
# 
# NOTE:       we apply small amount of regularization when we invert squared
#             Jacobian and calculate covariance matrix. It  guarantees  that
#             algorithm won't divide by zero  during  inversion,  but  skews
#             error estimates a bit (fractional error is about 10^-9).
# 
#             However, we believe that this difference is insignificant  for
#             all practical purposes except for the situation when you  want
#             to compare ALGLIB results with "reference"  implementation  up
#             to the last significant digit.
# 
# NOTE:       covariance matrix is estimated using  correction  for  degrees
#             of freedom (covariances are divided by N-M instead of dividing
#             by N).
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: info, c, rep = xalglib.lsfitresults(state)

Examples:   [1]  [2]  [3]  [4]  [5]  

lsfitsetbc function

#
# This function sets boundary constraints for underlying optimizer
# 
# Boundary constraints are inactive by default (after initial creation).
# They are preserved until explicitly turned off with another SetBC() call.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     BndL    -   lower bounds, array[K].
#                 If some (all) variables are unbounded, you may specify
#                 very small number or -INF (latter is recommended because
#                 it will allow solver to use better algorithm).
#     BndU    -   upper bounds, array[K].
#                 If some (all) variables are unbounded, you may specify
#                 very large number or +INF (latter is recommended because
#                 it will allow solver to use better algorithm).
# 
# NOTE 1: it is possible to specify BndL[i]=BndU[i]. In this case I-th
# variable will be "frozen" at X[i]=BndL[i]=BndU[i].
# 
# NOTE 2: unlike other constrained optimization algorithms, this solver  has
# following useful properties:
# * bound constraints are always satisfied exactly
# * function is evaluated only INSIDE area specified by bound constraints
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitsetbc(state, bndl, bndu)

lsfitsetcond function

#
# Stopping conditions for nonlinear least squares fitting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     EpsX    -   >=0
#                 The subroutine finishes its work if  on  k+1-th  iteration
#                 the condition |v|<=EpsX is fulfilled, where:
#                 * |.| means Euclidian norm
#                 * v - scaled step vector, v[i]=dx[i]/s[i]
#                 * dx - ste pvector, dx=X(k+1)-X(k)
#                 * s - scaling coefficients set by LSFitSetScale()
#     MaxIts  -   maximum number of iterations. If MaxIts=0, the  number  of
#                 iterations   is    unlimited.   Only   Levenberg-Marquardt
#                 iterations  are  counted  (L-BFGS/CG  iterations  are  NOT
#                 counted because their cost is very low compared to that of
#                 LM).
# 
# NOTE
# 
# Passing EpsX=0  and  MaxIts=0  (simultaneously)  will  lead  to  automatic
# stopping criterion selection (according to the scheme used by MINLM unit).
# 
# 
#   -- ALGLIB --
#      Copyright 17.08.2009 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitsetcond(state, epsx, maxits)

Examples:   [1]  [2]  [3]  [4]  [5]  

lsfitsetgradientcheck function

#
# This  subroutine  turns  on  verification  of  the  user-supplied analytic
# gradient:
# * user calls this subroutine before fitting begins
# * LSFitFit() is called
# * prior to actual fitting, for  each  point  in  data  set  X_i  and  each
#   component  of  parameters  being  fited C_j algorithm performs following
#   steps:
#   * two trial steps are made to C_j-TestStep*S[j] and C_j+TestStep*S[j],
#     where C_j is j-th parameter and S[j] is a scale of j-th parameter
#   * if needed, steps are bounded with respect to constraints on C[]
#   * F(X_i|C) is evaluated at these trial points
#   * we perform one more evaluation in the middle point of the interval
#   * we  build  cubic  model using function values and derivatives at trial
#     points and we compare its prediction with actual value in  the  middle
#     point
#   * in case difference between prediction and actual value is higher  than
#     some predetermined threshold, algorithm stops with completion code -7;
#     Rep.VarIdx is set to index of the parameter with incorrect derivative.
# * after verification is over, algorithm proceeds to the actual optimization.
# 
# NOTE 1: verification needs N*K (points count * parameters count)  gradient
#         evaluations. It is very costly and you should use it only for  low
#         dimensional  problems,  when  you  want  to  be  sure  that you've
#         correctly calculated analytic derivatives. You should not  use  it
#         in the production code  (unless  you  want  to  check  derivatives
#         provided by some third party).
# 
# NOTE 2: you  should  carefully  choose  TestStep. Value which is too large
#         (so large that function behaviour is significantly non-cubic) will
#         lead to false alarms. You may use  different  step  for  different
#         parameters by means of setting scale with LSFitSetScale().
# 
# NOTE 3: this function may lead to false positives. In case it reports that
#         I-th  derivative was calculated incorrectly, you may decrease test
#         step  and  try  one  more  time  - maybe your function changes too
#         sharply  and  your  step  is  too  large for such rapidly chanding
#         function.
# 
# NOTE 4: this function works only for optimizers created with LSFitCreateWFG()
#         or LSFitCreateFG() constructors.
# 
# INPUT PARAMETERS:
#     State       -   structure used to store algorithm state
#     TestStep    -   verification step:
#                     * TestStep=0 turns verification off
#                     * TestStep>0 activates verification
# 
#   -- ALGLIB --
#      Copyright 15.06.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitsetgradientcheck(state, teststep)

lsfitsetlc function

#
# This function sets linear constraints for underlying optimizer
# 
# Linear constraints are inactive by default (after initial creation).
# They are preserved until explicitly turned off with another SetLC() call.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     C       -   linear constraints, array[K,N+1].
#                 Each row of C represents one constraint, either equality
#                 or inequality (see below):
#                 * first N elements correspond to coefficients,
#                 * last element corresponds to the right part.
#                 All elements of C (including right part) must be finite.
#     CT      -   type of constraints, array[K]:
#                 * if CT[i]>0, then I-th constraint is C[i,*]*x >= C[i,n+1]
#                 * if CT[i]=0, then I-th constraint is C[i,*]*x  = C[i,n+1]
#                 * if CT[i]<0, then I-th constraint is C[i,*]*x <= C[i,n+1]
#     K       -   number of equality/inequality constraints, K>=0:
#                 * if given, only leading K elements of C/CT are used
#                 * if not given, automatically determined from sizes of C/CT
# 
# IMPORTANT: if you have linear constraints, it is strongly  recommended  to
#            set scale of variables with lsfitsetscale(). QP solver which is
#            used to calculate linearly constrained steps heavily relies  on
#            good scaling of input problems.
# 
# NOTE: linear  (non-box)  constraints  are  satisfied only approximately  -
#       there  always  exists some violation due  to  numerical  errors  and
#       algorithmic limitations.
# 
# NOTE: general linear constraints  add  significant  overhead  to  solution
#       process. Although solver performs roughly same amount of  iterations
#       (when compared  with  similar  box-only  constrained  problem), each
#       iteration   now    involves  solution  of  linearly  constrained  QP
#       subproblem, which requires ~3-5 times more Cholesky  decompositions.
#       Thus, if you can reformulate your problem in such way  this  it  has
#       only box constraints, it may be beneficial to do so.
# 
#   -- ALGLIB --
#      Copyright 29.04.2017 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitsetlc(state, c, ct, k)
SYNTAX: xalglib.lsfitsetlc(state, c, ct)

lsfitsetscale function

#
# This function sets scaling coefficients for underlying optimizer.
# 
# ALGLIB optimizers use scaling matrices to test stopping  conditions  (step
# size and gradient are scaled before comparison with tolerances).  Scale of
# the I-th variable is a translation invariant measure of:
# a) "how large" the variable is
# b) how large the step should be to make significant changes in the function
# 
# Generally, scale is NOT considered to be a form of preconditioner.  But LM
# optimizer is unique in that it uses scaling matrix both  in  the  stopping
# condition tests and as Marquardt damping factor.
# 
# Proper scaling is very important for the algorithm performance. It is less
# important for the quality of results, but still has some influence (it  is
# easier  to  converge  when  variables  are  properly  scaled, so premature
# stopping is possible when very badly scalled variables are  combined  with
# relaxed stopping conditions).
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     S       -   array[N], non-zero scaling coefficients
#                 S[i] may be negative, sign doesn't matter.
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitsetscale(state, s)

Examples:   [1]  

lsfitsetstpmax function

#
# This function sets maximum step length
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     StpMax  -   maximum step length, >=0. Set StpMax to 0.0,  if you don't
#                 want to limit step length.
# 
# Use this subroutine when you optimize target function which contains exp()
# or  other  fast  growing  functions,  and optimization algorithm makes too
# large  steps  which  leads  to overflow. This function allows us to reject
# steps  that  are  too  large  (and  therefore  expose  us  to the possible
# overflow) without actually calculating function value at the x+stp*d.
# 
# NOTE: non-zero StpMax leads to moderate  performance  degradation  because
# intermediate  step  of  preconditioned L-BFGS optimization is incompatible
# with limits on step size.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitsetstpmax(state, stpmax)

lsfitsetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# When reports are needed, State.C (current parameters) and State.F (current
# value of fitting function) are reported.
# 
# 
#   -- ALGLIB --
#      Copyright 15.08.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.lsfitsetxrep(state, needxrep)

lstfitpiecewiselinearrdp function

#
# This  subroutine fits piecewise linear curve to points with Ramer-Douglas-
# Peucker algorithm, which stops after achieving desired precision.
# 
# IMPORTANT:
# * it performs non-least-squares fitting; it builds curve, but  this  curve
#   does not minimize some least squares  metric.  See  description  of  RDP
#   algorithm (say, in Wikipedia) for more details on WHAT is performed.
# * this function does NOT work with parametric curves  (i.e.  curves  which
#   can be represented as {X(t),Y(t)}. It works with curves   which  can  be
#   represented as Y(X). Thus, it is impossible to model figures like circles
#   with this functions.
#   If  you  want  to  work  with  parametric   curves,   you   should   use
#   ParametricRDPFixed() function provided  by  "Parametric"  subpackage  of
#   "Interpolation" package.
# 
# INPUT PARAMETERS:
#     X       -   array of X-coordinates:
#                 * at least N elements
#                 * can be unordered (points are automatically sorted)
#                 * this function may accept non-distinct X (see below for
#                   more information on handling of such inputs)
#     Y       -   array of Y-coordinates:
#                 * at least N elements
#     N       -   number of elements in X/Y
#     Eps     -   positive number, desired precision.
# 
# 
# OUTPUT PARAMETERS:
#     X2      -   X-values of corner points for piecewise approximation,
#                 has length NSections+1 or zero (for NSections=0).
#     Y2      -   Y-values of corner points,
#                 has length NSections+1 or zero (for NSections=0).
#     NSections-  number of sections found by algorithm,
#                 NSections can be zero for degenerate datasets
#                 (N<=1 or all X[] are non-distinct).
# 
# NOTE: X2/Y2 are ordered arrays, i.e. (X2[0],Y2[0]) is  a  first  point  of
#       curve, (X2[NSection-1],Y2[NSection-1]) is the last point.
# 
#   -- ALGLIB --
#      Copyright 02.10.2014 by Bochkanov Sergey
#

SYNTAX: x2, y2, nsections = xalglib.lstfitpiecewiselinearrdp(x, y, n, eps)

lstfitpiecewiselinearrdpfixed function

#
# This  subroutine fits piecewise linear curve to points with Ramer-Douglas-
# Peucker algorithm, which stops after generating specified number of linear
# sections.
# 
# IMPORTANT:
# * it does NOT perform least-squares fitting; it  builds  curve,  but  this
#   curve does not minimize some least squares metric.  See  description  of
#   RDP algorithm (say, in Wikipedia) for more details on WHAT is performed.
# * this function does NOT work with parametric curves  (i.e.  curves  which
#   can be represented as {X(t),Y(t)}. It works with curves   which  can  be
#   represented as Y(X). Thus,  it  is  impossible  to  model  figures  like
#   circles  with  this  functions.
#   If  you  want  to  work  with  parametric   curves,   you   should   use
#   ParametricRDPFixed() function provided  by  "Parametric"  subpackage  of
#   "Interpolation" package.
# 
# INPUT PARAMETERS:
#     X       -   array of X-coordinates:
#                 * at least N elements
#                 * can be unordered (points are automatically sorted)
#                 * this function may accept non-distinct X (see below for
#                   more information on handling of such inputs)
#     Y       -   array of Y-coordinates:
#                 * at least N elements
#     N       -   number of elements in X/Y
#     M       -   desired number of sections:
#                 * at most M sections are generated by this function
#                 * less than M sections can be generated if we have N<M
#                   (or some X are non-distinct).
# 
# OUTPUT PARAMETERS:
#     X2      -   X-values of corner points for piecewise approximation,
#                 has length NSections+1 or zero (for NSections=0).
#     Y2      -   Y-values of corner points,
#                 has length NSections+1 or zero (for NSections=0).
#     NSections-  number of sections found by algorithm, NSections<=M,
#                 NSections can be zero for degenerate datasets
#                 (N<=1 or all X[] are non-distinct).
# 
# NOTE: X2/Y2 are ordered arrays, i.e. (X2[0],Y2[0]) is  a  first  point  of
#       curve, (X2[NSection-1],Y2[NSection-1]) is the last point.
# 
#   -- ALGLIB --
#      Copyright 02.10.2014 by Bochkanov Sergey
#

SYNTAX: x2, y2, nsections = xalglib.lstfitpiecewiselinearrdpfixed(x, y, n, m)

polynomialfit function

#
# Fitting by polynomials in barycentric form. This function provides  simple
# unterface for unconstrained unweighted fitting. See  PolynomialFitWC()  if
# you need constrained fitting.
# 
# Task is linear, so linear least squares solver is used. Complexity of this
# computational scheme is O(N*M^2), mostly dominated by least squares solver
# 
# SEE ALSO:
#     PolynomialFitWC()
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     N   -   number of points, N>0
#             * if given, only leading N elements of X/Y are used
#             * if not given, automatically determined from sizes of X/Y
#     M   -   number of basis functions (= polynomial_degree + 1), M>=1
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearW() subroutine:
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD
#     P   -   interpolant in barycentric form.
#     Rep -   report, same format as in LSFitLinearW() subroutine.
#             Following fields are set:
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
# NOTES:
#     you can convert P from barycentric form  to  the  power  or  Chebyshev
#     basis with PolynomialBar2Pow() or PolynomialBar2Cheb() functions  from
#     POLINT subpackage.
# 
#   -- ALGLIB PROJECT --
#      Copyright 10.12.2009 by Bochkanov Sergey
#

SYNTAX: info, p, rep = xalglib.polynomialfit(x, y, n, m)
SYNTAX: info, p, rep = xalglib.polynomialfit(x, y, m)
SYNTAX: info, p, rep = xalglib.smp_polynomialfit(x, y, n, m)
SYNTAX: info, p, rep = xalglib.smp_polynomialfit(x, y, m)

Examples:   [1]  

polynomialfitwc function

#
# Weighted  fitting by polynomials in barycentric form, with constraints  on
# function values or first derivatives.
# 
# Small regularizing term is used when solving constrained tasks (to improve
# stability).
# 
# Task is linear, so linear least squares solver is used. Complexity of this
# computational scheme is O(N*M^2), mostly dominated by least squares solver
# 
# SEE ALSO:
#     PolynomialFit()
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     W   -   weights, array[0..N-1]
#             Each summand in square  sum  of  approximation deviations from
#             given  values  is  multiplied  by  the square of corresponding
#             weight. Fill it by 1's if you don't  want  to  solve  weighted
#             task.
#     N   -   number of points, N>0.
#             * if given, only leading N elements of X/Y/W are used
#             * if not given, automatically determined from sizes of X/Y/W
#     XC  -   points where polynomial values/derivatives are constrained,
#             array[0..K-1].
#     YC  -   values of constraints, array[0..K-1]
#     DC  -   array[0..K-1], types of constraints:
#             * DC[i]=0   means that P(XC[i])=YC[i]
#             * DC[i]=1   means that P'(XC[i])=YC[i]
#             SEE BELOW FOR IMPORTANT INFORMATION ON CONSTRAINTS
#     K   -   number of constraints, 0<=K<M.
#             K=0 means no constraints (XC/YC/DC are not used in such cases)
#     M   -   number of basis functions (= polynomial_degree + 1), M>=1
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearW() subroutine:
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD
#                         -3 means inconsistent constraints
#     P   -   interpolant in barycentric form.
#     Rep -   report, same format as in LSFitLinearW() subroutine.
#             Following fields are set:
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroitine doesn't calculate task's condition number for K<>0.
# 
# NOTES:
#     you can convert P from barycentric form  to  the  power  or  Chebyshev
#     basis with PolynomialBar2Pow() or PolynomialBar2Cheb() functions  from
#     POLINT subpackage.
# 
# SETTING CONSTRAINTS - DANGERS AND OPPORTUNITIES:
# 
# Setting constraints can lead  to undesired  results,  like ill-conditioned
# behavior, or inconsistency being detected. From the other side,  it allows
# us to improve quality of the fit. Here we summarize  our  experience  with
# constrained regression splines:
# * even simple constraints can be inconsistent, see  Wikipedia  article  on
#   this subject: http://en.wikipedia.org/wiki/Birkhoff_interpolation
# * the  greater  is  M (given  fixed  constraints),  the  more chances that
#   constraints will be consistent
# * in the general case, consistency of constraints is NOT GUARANTEED.
# * in the one special cases, however, we can  guarantee  consistency.  This
#   case  is:  M>1  and constraints on the function values (NOT DERIVATIVES)
# 
# Our final recommendation is to use constraints  WHEN  AND  ONLY  when  you
# can't solve your task without them. Anything beyond  special  cases  given
# above is not guaranteed and may result in inconsistency.
# 
#   -- ALGLIB PROJECT --
#      Copyright 10.12.2009 by Bochkanov Sergey
#

SYNTAX: info, p, rep = xalglib.polynomialfitwc(x, y, w, n, xc, yc, dc, k, m)
SYNTAX: info, p, rep = xalglib.polynomialfitwc(x, y, w, xc, yc, dc, m)
SYNTAX: info, p, rep = xalglib.smp_polynomialfitwc(x, y, w, n, xc, yc, dc, k, m)
SYNTAX: info, p, rep = xalglib.smp_polynomialfitwc(x, y, w, xc, yc, dc, m)

Examples:   [1]  

spline1dfitcubic function

#
# Least squares fitting by cubic spline.
# 
# This subroutine is "lightweight" alternative for more complex and feature-
# rich Spline1DFitCubicWC().  See  Spline1DFitCubicWC() for more information
# about subroutine parameters (we don't duplicate it here because of length)
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
#   -- ALGLIB PROJECT --
#      Copyright 18.08.2009 by Bochkanov Sergey
#

SYNTAX: info, s, rep = xalglib.spline1dfitcubic(x, y, n, m)
SYNTAX: info, s, rep = xalglib.spline1dfitcubic(x, y, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitcubic(x, y, n, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitcubic(x, y, m)

spline1dfitcubicwc function

#
# Weighted fitting by cubic  spline,  with constraints on function values or
# derivatives.
# 
# Equidistant grid with M-2 nodes on [min(x,xc),max(x,xc)] is  used to build
# basis functions. Basis functions are cubic splines with continuous  second
# derivatives  and  non-fixed first  derivatives  at  interval  ends.  Small
# regularizing term is used  when  solving  constrained  tasks  (to  improve
# stability).
# 
# Task is linear, so linear least squares solver is used. Complexity of this
# computational scheme is O(N*M^2), mostly dominated by least squares solver
# 
# SEE ALSO
#     Spline1DFitHermiteWC()  -   fitting by Hermite splines (more flexible,
#                                 less smooth)
#     Spline1DFitCubic()      -   "lightweight" fitting  by  cubic  splines,
#                                 without invididual weights and constraints
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     W   -   weights, array[0..N-1]
#             Each summand in square  sum  of  approximation deviations from
#             given  values  is  multiplied  by  the square of corresponding
#             weight. Fill it by 1's if you don't  want  to  solve  weighted
#             task.
#     N   -   number of points (optional):
#             * N>0
#             * if given, only first N elements of X/Y/W are processed
#             * if not given, automatically determined from X/Y/W sizes
#     XC  -   points where spline values/derivatives are constrained,
#             array[0..K-1].
#     YC  -   values of constraints, array[0..K-1]
#     DC  -   array[0..K-1], types of constraints:
#             * DC[i]=0   means that S(XC[i])=YC[i]
#             * DC[i]=1   means that S'(XC[i])=YC[i]
#             SEE BELOW FOR IMPORTANT INFORMATION ON CONSTRAINTS
#     K   -   number of constraints (optional):
#             * 0<=K<M.
#             * K=0 means no constraints (XC/YC/DC are not used)
#             * if given, only first K elements of XC/YC/DC are used
#             * if not given, automatically determined from XC/YC/DC
#     M   -   number of basis functions ( = number_of_nodes+2), M>=4.
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearWC() subroutine.
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD
#                         -3 means inconsistent constraints
#     S   -   spline interpolant.
#     Rep -   report, same format as in LSFitLinearWC() subroutine.
#             Following fields are set:
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroitine doesn't calculate task's condition number for K<>0.
# 
# 
# ORDER OF POINTS
# 
# Subroutine automatically sorts points, so caller may pass unsorted array.
# 
# SETTING CONSTRAINTS - DANGERS AND OPPORTUNITIES:
# 
# Setting constraints can lead  to undesired  results,  like ill-conditioned
# behavior, or inconsistency being detected. From the other side,  it allows
# us to improve quality of the fit. Here we summarize  our  experience  with
# constrained regression splines:
# * excessive constraints can be inconsistent. Splines are  piecewise  cubic
#   functions, and it is easy to create an example, where  large  number  of
#   constraints  concentrated  in  small  area will result in inconsistency.
#   Just because spline is not flexible enough to satisfy all of  them.  And
#   same constraints spread across the  [min(x),max(x)]  will  be  perfectly
#   consistent.
# * the more evenly constraints are spread across [min(x),max(x)],  the more
#   chances that they will be consistent
# * the  greater  is  M (given  fixed  constraints),  the  more chances that
#   constraints will be consistent
# * in the general case, consistency of constraints IS NOT GUARANTEED.
# * in the several special cases, however, we CAN guarantee consistency.
# * one of this cases is constraints  on  the  function  values  AND/OR  its
#   derivatives at the interval boundaries.
# * another  special  case  is ONE constraint on the function value (OR, but
#   not AND, derivative) anywhere in the interval
# 
# Our final recommendation is to use constraints  WHEN  AND  ONLY  WHEN  you
# can't solve your task without them. Anything beyond  special  cases  given
# above is not guaranteed and may result in inconsistency.
# 
# 
#   -- ALGLIB PROJECT --
#      Copyright 18.08.2009 by Bochkanov Sergey
#

SYNTAX: info, s, rep = xalglib.spline1dfitcubicwc(x, y, w, n, xc, yc, dc, k, m)
SYNTAX: info, s, rep = xalglib.spline1dfitcubicwc(x, y, w, xc, yc, dc, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitcubicwc(x, y, w, n, xc, yc, dc, k, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitcubicwc(x, y, w, xc, yc, dc, m)

spline1dfithermite function

#
# Least squares fitting by Hermite spline.
# 
# This subroutine is "lightweight" alternative for more complex and feature-
# rich Spline1DFitHermiteWC().  See Spline1DFitHermiteWC()  description  for
# more information about subroutine parameters (we don't duplicate  it  here
# because of length).
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
#   -- ALGLIB PROJECT --
#      Copyright 18.08.2009 by Bochkanov Sergey
#

SYNTAX: info, s, rep = xalglib.spline1dfithermite(x, y, n, m)
SYNTAX: info, s, rep = xalglib.spline1dfithermite(x, y, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfithermite(x, y, n, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfithermite(x, y, m)

spline1dfithermitewc function

#
# Weighted  fitting  by Hermite spline,  with constraints on function values
# or first derivatives.
# 
# Equidistant grid with M nodes on [min(x,xc),max(x,xc)] is  used  to  build
# basis functions. Basis functions are Hermite splines.  Small  regularizing
# term is used when solving constrained tasks (to improve stability).
# 
# Task is linear, so linear least squares solver is used. Complexity of this
# computational scheme is O(N*M^2), mostly dominated by least squares solver
# 
# SEE ALSO
#     Spline1DFitCubicWC()    -   fitting by Cubic splines (less flexible,
#                                 more smooth)
#     Spline1DFitHermite()    -   "lightweight" Hermite fitting, without
#                                 invididual weights and constraints
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     W   -   weights, array[0..N-1]
#             Each summand in square  sum  of  approximation deviations from
#             given  values  is  multiplied  by  the square of corresponding
#             weight. Fill it by 1's if you don't  want  to  solve  weighted
#             task.
#     N   -   number of points (optional):
#             * N>0
#             * if given, only first N elements of X/Y/W are processed
#             * if not given, automatically determined from X/Y/W sizes
#     XC  -   points where spline values/derivatives are constrained,
#             array[0..K-1].
#     YC  -   values of constraints, array[0..K-1]
#     DC  -   array[0..K-1], types of constraints:
#             * DC[i]=0   means that S(XC[i])=YC[i]
#             * DC[i]=1   means that S'(XC[i])=YC[i]
#             SEE BELOW FOR IMPORTANT INFORMATION ON CONSTRAINTS
#     K   -   number of constraints (optional):
#             * 0<=K<M.
#             * K=0 means no constraints (XC/YC/DC are not used)
#             * if given, only first K elements of XC/YC/DC are used
#             * if not given, automatically determined from XC/YC/DC
#     M   -   number of basis functions (= 2 * number of nodes),
#             M>=4,
#             M IS EVEN!
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearW() subroutine:
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD
#                         -3 means inconsistent constraints
#                         -2 means odd M was passed (which is not supported)
#                         -1 means another errors in parameters passed
#                            (N<=0, for example)
#     S   -   spline interpolant.
#     Rep -   report, same format as in LSFitLinearW() subroutine.
#             Following fields are set:
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroitine doesn't calculate task's condition number for K<>0.
# 
# IMPORTANT:
#     this subroitine supports only even M's
# 
# 
# ORDER OF POINTS
# 
# Subroutine automatically sorts points, so caller may pass unsorted array.
# 
# SETTING CONSTRAINTS - DANGERS AND OPPORTUNITIES:
# 
# Setting constraints can lead  to undesired  results,  like ill-conditioned
# behavior, or inconsistency being detected. From the other side,  it allows
# us to improve quality of the fit. Here we summarize  our  experience  with
# constrained regression splines:
# * excessive constraints can be inconsistent. Splines are  piecewise  cubic
#   functions, and it is easy to create an example, where  large  number  of
#   constraints  concentrated  in  small  area will result in inconsistency.
#   Just because spline is not flexible enough to satisfy all of  them.  And
#   same constraints spread across the  [min(x),max(x)]  will  be  perfectly
#   consistent.
# * the more evenly constraints are spread across [min(x),max(x)],  the more
#   chances that they will be consistent
# * the  greater  is  M (given  fixed  constraints),  the  more chances that
#   constraints will be consistent
# * in the general case, consistency of constraints is NOT GUARANTEED.
# * in the several special cases, however, we can guarantee consistency.
# * one of this cases is  M>=4  and   constraints  on   the  function  value
#   (AND/OR its derivative) at the interval boundaries.
# * another special case is M>=4  and  ONE  constraint on the function value
#   (OR, BUT NOT AND, derivative) anywhere in [min(x),max(x)]
# 
# Our final recommendation is to use constraints  WHEN  AND  ONLY  when  you
# can't solve your task without them. Anything beyond  special  cases  given
# above is not guaranteed and may result in inconsistency.
# 
#   -- ALGLIB PROJECT --
#      Copyright 18.08.2009 by Bochkanov Sergey
#

SYNTAX: info, s, rep = xalglib.spline1dfithermitewc(x, y, w, n, xc, yc, dc, k, m)
SYNTAX: info, s, rep = xalglib.spline1dfithermitewc(x, y, w, xc, yc, dc, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfithermitewc(x, y, w, n, xc, yc, dc, k, m)
SYNTAX: info, s, rep = xalglib.smp_spline1dfithermitewc(x, y, w, xc, yc, dc, m)

spline1dfitpenalized function

#
# Fitting by penalized cubic spline.
# 
# Equidistant grid with M nodes on [min(x,xc),max(x,xc)] is  used  to  build
# basis functions. Basis functions are cubic splines with  natural  boundary
# conditions. Problem is regularized by  adding non-linearity penalty to the
# usual least squares penalty function:
# 
#     S(x) = arg min { LS + P }, where
#     LS   = SUM { w[i]^2*(y[i] - S(x[i]))^2 } - least squares penalty
#     P    = C*10^rho*integral{ S''(x)^2*dx } - non-linearity penalty
#     rho  - tunable constant given by user
#     C    - automatically determined scale parameter,
#            makes penalty invariant with respect to scaling of X, Y, W.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     N   -   number of points (optional):
#             * N>0
#             * if given, only first N elements of X/Y are processed
#             * if not given, automatically determined from X/Y sizes
#     M   -   number of basis functions ( = number_of_nodes), M>=4.
#     Rho -   regularization  constant  passed   by   user.   It   penalizes
#             nonlinearity in the regression spline. It  is  logarithmically
#             scaled,  i.e.  actual  value  of  regularization  constant  is
#             calculated as 10^Rho. It is automatically scaled so that:
#             * Rho=2.0 corresponds to moderate amount of nonlinearity
#             * generally, it should be somewhere in the [-8.0,+8.0]
#             If you do not want to penalize nonlineary,
#             pass small Rho. Values as low as -15 should work.
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearWC() subroutine.
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD or
#                            Cholesky decomposition; problem may be
#                            too ill-conditioned (very rare)
#     S   -   spline interpolant.
#     Rep -   Following fields are set:
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroitine doesn't calculate task's condition number for K<>0.
# 
# NOTE 1: additional nodes are added to the spline outside  of  the  fitting
# interval to force linearity when x<min(x,xc) or x>max(x,xc).  It  is  done
# for consistency - we penalize non-linearity  at [min(x,xc),max(x,xc)],  so
# it is natural to force linearity outside of this interval.
# 
# NOTE 2: function automatically sorts points,  so  caller may pass unsorted
# array.
# 
#   -- ALGLIB PROJECT --
#      Copyright 18.08.2009 by Bochkanov Sergey
#

SYNTAX: info, s, rep = xalglib.spline1dfitpenalized(x, y, n, m, rho)
SYNTAX: info, s, rep = xalglib.spline1dfitpenalized(x, y, m, rho)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitpenalized(x, y, n, m, rho)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitpenalized(x, y, m, rho)

Examples:   [1]  

spline1dfitpenalizedw function

#
# Weighted fitting by penalized cubic spline.
# 
# Equidistant grid with M nodes on [min(x,xc),max(x,xc)] is  used  to  build
# basis functions. Basis functions are cubic splines with  natural  boundary
# conditions. Problem is regularized by  adding non-linearity penalty to the
# usual least squares penalty function:
# 
#     S(x) = arg min { LS + P }, where
#     LS   = SUM { w[i]^2*(y[i] - S(x[i]))^2 } - least squares penalty
#     P    = C*10^rho*integral{ S''(x)^2*dx } - non-linearity penalty
#     rho  - tunable constant given by user
#     C    - automatically determined scale parameter,
#            makes penalty invariant with respect to scaling of X, Y, W.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multithreading support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Speed-up provided by multithreading greatly depends  on  problem  size
#   ! - only large problems (number of coefficients is more than 500) can be
#   ! efficiently multithreaded.
#   !
#   ! Generally, commercial ALGLIB is several times faster than  open-source
#   ! generic C edition, and many times faster than open-source C# edition.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     X   -   points, array[0..N-1].
#     Y   -   function values, array[0..N-1].
#     W   -   weights, array[0..N-1]
#             Each summand in square  sum  of  approximation deviations from
#             given  values  is  multiplied  by  the square of corresponding
#             weight. Fill it by 1's if you don't  want  to  solve  weighted
#             problem.
#     N   -   number of points (optional):
#             * N>0
#             * if given, only first N elements of X/Y/W are processed
#             * if not given, automatically determined from X/Y/W sizes
#     M   -   number of basis functions ( = number_of_nodes), M>=4.
#     Rho -   regularization  constant  passed   by   user.   It   penalizes
#             nonlinearity in the regression spline. It  is  logarithmically
#             scaled,  i.e.  actual  value  of  regularization  constant  is
#             calculated as 10^Rho. It is automatically scaled so that:
#             * Rho=2.0 corresponds to moderate amount of nonlinearity
#             * generally, it should be somewhere in the [-8.0,+8.0]
#             If you do not want to penalize nonlineary,
#             pass small Rho. Values as low as -15 should work.
# 
# OUTPUT PARAMETERS:
#     Info-   same format as in LSFitLinearWC() subroutine.
#             * Info>0    task is solved
#             * Info<=0   an error occured:
#                         -4 means inconvergence of internal SVD or
#                            Cholesky decomposition; problem may be
#                            too ill-conditioned (very rare)
#     S   -   spline interpolant.
#     Rep -   Following fields are set:
#             * RMSError      rms error on the (X,Y).
#             * AvgError      average error on the (X,Y).
#             * AvgRelError   average relative error on the non-zero Y
#             * MaxError      maximum error
#                             NON-WEIGHTED ERRORS ARE CALCULATED
# 
# IMPORTANT:
#     this subroitine doesn't calculate task's condition number for K<>0.
# 
# NOTE 1: additional nodes are added to the spline outside  of  the  fitting
# interval to force linearity when x<min(x,xc) or x>max(x,xc).  It  is  done
# for consistency - we penalize non-linearity  at [min(x,xc),max(x,xc)],  so
# it is natural to force linearity outside of this interval.
# 
# NOTE 2: function automatically sorts points,  so  caller may pass unsorted
# array.
# 
#   -- ALGLIB PROJECT --
#      Copyright 19.10.2010 by Bochkanov Sergey
#

SYNTAX: info, s, rep = xalglib.spline1dfitpenalizedw(x, y, w, n, m, rho)
SYNTAX: info, s, rep = xalglib.spline1dfitpenalizedw(x, y, w, m, rho)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitpenalizedw(x, y, w, n, m, rho)
SYNTAX: info, s, rep = xalglib.smp_spline1dfitpenalizedw(x, y, w, m, rho)

Examples:   [1]  

lsfit_d_lin example

import xalglib



#
# In this example we demonstrate linear fitting by f(x|a) = a*exp(0.5*x).
#
# We have:
# * y - vector of experimental data
# * fmatrix -  matrix of basis functions calculated at sample points
#              Actually, we have only one basis function F0 = exp(0.5*x).
#
fmatrix = [[0.606531],[0.670320],[0.740818],[0.818731],[0.904837],[1.000000],[1.105171],[1.221403],[1.349859],[1.491825],[1.648721]]
y = [1.133719, 1.306522, 1.504604, 1.554663, 1.884638, 2.072436, 2.257285, 2.534068, 2.622017, 2.897713, 3.219371]

#
# Linear fitting without weights
#
info, c, rep = xalglib.lsfitlinear(y, fmatrix)
print(info) # expected 1
print(c) # expected [1.98650]

#
# Linear fitting with individual weights.
# Slightly different result is returned.
#
w = [1.414213, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]
info, c, rep = xalglib.lsfitlinearw(y, w, fmatrix)
print(info) # expected 1
print(c) # expected [1.983354]

lsfit_d_linc example

import xalglib



#
# In this example we demonstrate linear fitting by f(x|a,b) = a*x+b
# with simple constraint f(0)=0.
#
# We have:
# * y - vector of experimental data
# * fmatrix -  matrix of basis functions sampled at [0,1] with step 0.2:
#                  [ 1.0   0.0 ]
#                  [ 1.0   0.2 ]
#                  [ 1.0   0.4 ]
#                  [ 1.0   0.6 ]
#                  [ 1.0   0.8 ]
#                  [ 1.0   1.0 ]
#              first column contains value of first basis function (constant term)
#              second column contains second basis function (linear term)
# * cmatrix -  matrix of linear constraints:
#                  [ 1.0  0.0  0.0 ]
#              first two columns contain coefficients before basis functions,
#              last column contains desired value of their sum.
#              So [1,0,0] means "1*constant_term + 0*linear_term = 0" 
#
y = [0.072436,0.246944,0.491263,0.522300,0.714064,0.921929]
fmatrix = [[1,0.0],[1,0.2],[1,0.4],[1,0.6],[1,0.8],[1,1.0]]
cmatrix = [[1,0,0]]

#
# Constrained fitting without weights
#
info, c, rep = xalglib.lsfitlinearc(y, fmatrix, cmatrix)
print(info) # expected 1
print(c) # expected [0,0.932933]

#
# Constrained fitting with individual weights
#
w = [1, 1.414213, 1, 1, 1, 1]
info, c, rep = xalglib.lsfitlinearwc(y, w, fmatrix, cmatrix)
print(info) # expected 1
print(c) # expected [0,0.938322]

lsfit_d_nlf example

import xalglib

def function_cx_1_func(c, x, param):
    #
    # this callback calculates f(c,x)=exp(-c0*sqr(x0))
    # where x is a position on X-axis and c is adjustable parameter
    #
    return math.exp(-c[0]*(x[0])**2)

#
# In this example we demonstrate exponential fitting
# by f(x) = exp(-c*x^2)
# using function value only.
#
# Gradient is estimated using combination of numerical differences
# and secant updates. diffstep variable stores differentiation step 
# (we have to tell algorithm what step to use).
#
x = [[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]
y = [0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582748, 0.382893, 0.223130]
c = [0.3]
epsx = 0.000001
maxits = 0
diffstep = 0.0001

#
# Fitting without weights
#
state = xalglib.lsfitcreatef(x, y, c, diffstep)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitfit_f(state, function_cx_1_func)
info, c, rep = xalglib.lsfitresults(state)
print(info) # expected 2
print(c) # expected [1.5]

#
# Fitting with weights
# (you can change weights and see how it changes result)
#
w = [1,1,1,1,1,1,1,1,1,1,1]
state = xalglib.lsfitcreatewf(x, y, w, c, diffstep)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitfit_f(state, function_cx_1_func)
info, c, rep = xalglib.lsfitresults(state)
print(info) # expected 2
print(c) # expected [1.5]

lsfit_d_nlfb example

import xalglib

def function_cx_1_func(c, x, param):
    #
    # this callback calculates f(c,x)=exp(-c0*sqr(x0))
    # where x is a position on X-axis and c is adjustable parameter
    #
    return math.exp(-c[0]*(x[0])**2)

#
# In this example we demonstrate exponential fitting by
#     f(x) = exp(-c*x^2)
# subject to bound constraints
#     0.0 <= c <= 1.0
# using function value only.
#
# Gradient is estimated using combination of numerical differences
# and secant updates. diffstep variable stores differentiation step 
# (we have to tell algorithm what step to use).
#
# Unconstrained solution is c=1.5, but because of constraints we should
# get c=1.0 (at the boundary).
#
x = [[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]
y = [0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582748, 0.382893, 0.223130]
c = [0.3]
bndl = [0.0]
bndu = [1.0]
epsx = 0.000001
maxits = 0
diffstep = 0.0001

state = xalglib.lsfitcreatef(x, y, c, diffstep)
xalglib.lsfitsetbc(state, bndl, bndu)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitfit_f(state, function_cx_1_func)
info, c, rep = xalglib.lsfitresults(state)
print(c) # expected [1.0]

lsfit_d_nlfg example

import xalglib

def function_cx_1_func(c, x, param):
    #
    # this callback calculates f(c,x)=exp(-c0*sqr(x0))
    # where x is a position on X-axis and c is adjustable parameter
    #
    return math.exp(-c[0]*(x[0])**2)

def function_cx_1_grad(c, x, grad, param):
    #
    # this callback calculates f(c,x)=exp(-c0*sqr(x0)) and gradient G={df/dc[i]}
    # where x is a position on X-axis and c is adjustable parameter.
    # IMPORTANT: gradient is calculated with respect to C, not to X
    #
    func = math.exp(-c[0]*(x[0])**2)
    grad[0] = -((x[0])**2)*func
    return func

#
# In this example we demonstrate exponential fitting
# by f(x) = exp(-c*x^2)
# using function value and gradient (with respect to c).
#
x = [[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]
y = [0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582748, 0.382893, 0.223130]
c = [0.3]
epsx = 0.000001
maxits = 0

#
# Fitting without weights
#
state = xalglib.lsfitcreatefg(x, y, c, True)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitfit_fg(state, function_cx_1_func, function_cx_1_grad)
info, c, rep = xalglib.lsfitresults(state)
print(info) # expected 2
print(c) # expected [1.5]

#
# Fitting with weights
# (you can change weights and see how it changes result)
#
w = [1,1,1,1,1,1,1,1,1,1,1]
state = xalglib.lsfitcreatewfg(x, y, w, c, True)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitfit_fg(state, function_cx_1_func, function_cx_1_grad)
info, c, rep = xalglib.lsfitresults(state)
print(info) # expected 2
print(c) # expected [1.5]

lsfit_d_nlfgh example

import xalglib

def function_cx_1_func(c, x, param):
    #
    # this callback calculates f(c,x)=exp(-c0*sqr(x0))
    # where x is a position on X-axis and c is adjustable parameter
    #
    return math.exp(-c[0]*(x[0])**2)

def function_cx_1_grad(c, x, grad, param):
    #
    # this callback calculates f(c,x)=exp(-c0*sqr(x0)) and gradient G={df/dc[i]}
    # where x is a position on X-axis and c is adjustable parameter.
    # IMPORTANT: gradient is calculated with respect to C, not to X
    #
    func = math.exp(-c[0]*(x[0])**2)
    grad[0] = -((x[0])**2)*func
    return func

def function_cx_1_hess(c, x, grad, hess, param):
    #
    # this callback calculates f(c,x)=exp(-c0*sqr(x0)), gradient G={df/dc[i]} and Hessian H={d2f/(dc[i]*dc[j])}
    # where x is a position on X-axis and c is adjustable parameter.
    # IMPORTANT: gradient/Hessian are calculated with respect to C, not to X
    #
    func = math.exp(-c[0]*(x[0])**2)
    grad[0] = -((x[0])**2)*func
    hess[0][0] = ((x[0])**4)*func
    return func

#
# In this example we demonstrate exponential fitting
# by f(x) = exp(-c*x^2)
# using function value, gradient and Hessian (with respect to c)
#
x = [[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]
y = [0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582748, 0.382893, 0.223130]
c = [0.3]
epsx = 0.000001
maxits = 0

#
# Fitting without weights
#
state = xalglib.lsfitcreatefgh(x, y, c)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitfit_fgh(state, function_cx_1_func, function_cx_1_grad, function_cx_1_hess)
info, c, rep = xalglib.lsfitresults(state)
print(info) # expected 2
print(c) # expected [1.5]

#
# Fitting with weights
# (you can change weights and see how it changes result)
#
w = [1,1,1,1,1,1,1,1,1,1,1]
state = xalglib.lsfitcreatewfgh(x, y, w, c)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitfit_fgh(state, function_cx_1_func, function_cx_1_grad, function_cx_1_hess)
info, c, rep = xalglib.lsfitresults(state)
print(info) # expected 2
print(c) # expected [1.5]

lsfit_d_nlscale example

import xalglib

def function_debt_func(c, x, param):
    #
    # this callback calculates f(c,x)=c[0]*(1+c[1]*(pow(x[0]-1999,c[2])-1))
    #
    return c[0]*(1+c[1]*((x[0]-1999)**c[2]-1))

#
# In this example we demonstrate fitting by
#     f(x) = c[0]*(1+c[1]*((x-1999)^c[2]-1))
# subject to bound constraints
#     -INF  < c[0] < +INF
#      -10 <= c[1] <= +10
#      0.1 <= c[2] <= 2.0
# Data we want to fit are time series of Japan national debt
# collected from 2000 to 2008 measured in USD (dollars, not
# millions of dollars).
#
# Our variables are:
#     c[0] - debt value at initial moment (2000),
#     c[1] - direction coefficient (growth or decrease),
#     c[2] - curvature coefficient.
# You may see that our variables are badly scaled - first one 
# is order of 10^12, and next two are somewhere about 1 in 
# magnitude. Such problem is difficult to solve without some
# kind of scaling.
# That is exactly where lsfitsetscale() function can be used.
# We set scale of our variables to [1.0E12, 1, 1], which allows
# us to easily solve this problem.
#
# You can try commenting out lsfitsetscale() call - and you will 
# see that algorithm will fail to converge.
#
x = [[2000],[2001],[2002],[2003],[2004],[2005],[2006],[2007],[2008]]
y = [4323239600000.0, 4560913100000.0, 5564091500000.0, 6743189300000.0, 7284064600000.0, 7050129600000.0, 7092221500000.0, 8483907600000.0, 8625804400000.0]
c = [1.0e+13, 1, 1]
epsx = 1.0e-5
bndl = [-float("inf"), -10, 0.1]
bndu = [float("inf"), +10, 2.0]
s = [1.0e+12, 1, 1]
maxits = 0
diffstep = 1.0e-5

state = xalglib.lsfitcreatef(x, y, c, diffstep)
xalglib.lsfitsetcond(state, epsx, maxits)
xalglib.lsfitsetbc(state, bndl, bndu)
xalglib.lsfitsetscale(state, s)
xalglib.lsfitfit_f(state, function_debt_func)
info, c, rep = xalglib.lsfitresults(state)
print(info) # expected 2
print(c) # expected [4.142560e+12, 0.434240, 0.565376]

lsfit_d_pol example

import xalglib



#
# This example demonstrates polynomial fitting.
#
# Fitting is done by two (M=2) functions from polynomial basis:
#     f0 = 1
#     f1 = x
# Basically, it just a linear fit; more complex polynomials may be used
# (e.g. parabolas with M=3, cubic with M=4), but even such simple fit allows
# us to demonstrate polynomialfit() function in action.
#
# We have:
# * x      set of abscissas
# * y      experimental data
#
# Additionally we demonstrate weighted fitting, where second point has
# more weight than other ones.
#
x = [0.0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1.0]
y = [0.00,0.05,0.26,0.32,0.33,0.43,0.60,0.60,0.77,0.98,1.02]
m = 2
t = 2

#
# Fitting without individual weights
#
# NOTE: result is returned as barycentricinterpolant structure.
#       if you want to get representation in the power basis,
#       you can use barycentricbar2pow() function to convert
#       from barycentric to power representation (see docs for 
#       POLINT subpackage for more info).
#
info, p, rep = xalglib.polynomialfit(x, y, m)
v = xalglib.barycentriccalc(p, t)
print(v) # expected 2.011

#
# Fitting with individual weights
#
# NOTE: slightly different result is returned
#
w = [1,1.414213562,1,1,1,1,1,1,1,1,1]
xc = []
yc = []
dc = []
info, p, rep = xalglib.polynomialfitwc(x, y, w, xc, yc, dc, m)
v = xalglib.barycentriccalc(p, t)
print(v) # expected 2.023

lsfit_d_polc example

import xalglib



#
# This example demonstrates polynomial fitting.
#
# Fitting is done by two (M=2) functions from polynomial basis:
#     f0 = 1
#     f1 = x
# with simple constraint on function value
#     f(0) = 0
# Basically, it just a linear fit; more complex polynomials may be used
# (e.g. parabolas with M=3, cubic with M=4), but even such simple fit allows
# us to demonstrate polynomialfit() function in action.
#
# We have:
# * x      set of abscissas
# * y      experimental data
# * xc     points where constraints are placed
# * yc     constraints on derivatives
# * dc     derivative indices
#          (0 means function itself, 1 means first derivative)
#
x = [1.0,1.0]
y = [0.9,1.1]
w = [1,1]
xc = [0]
yc = [0]
dc = [0]
t = 2
m = 2

info, p, rep = xalglib.polynomialfitwc(x, y, w, xc, yc, dc, m)
v = xalglib.barycentriccalc(p, t)
print(v) # expected 2.000

lsfit_d_spline example

import xalglib



#
# In this example we demonstrate penalized spline fitting of noisy data
#
# We have:
# * x - abscissas
# * y - vector of experimental data, straight line with small noise
#
x = [0.00,0.10,0.20,0.30,0.40,0.50,0.60,0.70,0.80,0.90]
y = [0.10,0.00,0.30,0.40,0.30,0.40,0.62,0.68,0.75,0.95]

#
# Fit with VERY small amount of smoothing (rho = -5.0)
# and large number of basis functions (M=50).
#
# With such small regularization penalized spline almost fully reproduces function values
#
rho = -5.0
info, s, rep = xalglib.spline1dfitpenalized(x, y, 50, rho)
print(info) # expected 1
v = xalglib.spline1dcalc(s, 0.0)
print(v) # expected 0.10

#
# Fit with VERY large amount of smoothing (rho = 10.0)
# and large number of basis functions (M=50).
#
# With such regularization our spline should become close to the straight line fit.
# We will compare its value in x=1.0 with results obtained from such fit.
#
rho = +10.0
info, s, rep = xalglib.spline1dfitpenalized(x, y, 50, rho)
print(info) # expected 1
v = xalglib.spline1dcalc(s, 1.0)
print(v) # expected 0.969

#
# In real life applications you may need some moderate degree of fitting,
# so we try to fit once more with rho=3.0.
#
rho = +3.0
info, s, rep = xalglib.spline1dfitpenalized(x, y, 50, rho)
print(info) # expected 1

lsfit_t_4pl example

import xalglib



x = [1,2,3,4,5,6,7,8]
y = [0.06313223,0.44552624,0.61838364,0.71385108,0.77345838,0.81383140,0.84280033,0.86449822]
n = 8

#
# Test logisticfit4() on carefully designed data with a priori known answer.
#
a, b, c, d, rep = xalglib.logisticfit4(x, y, n)
print(a) # expected -1.000
print(b) # expected 1.200
print(c) # expected 0.900
print(d) # expected 1.000

#
# Evaluate model at point x=0.5
#
v = xalglib.logisticcalc4(0.5, a, b, c, d)
print(v) # expected -0.33874308

lsfit_t_5pl example

import xalglib



x = [1,2,3,4,5,6,7,8]
y = [0.1949776139,0.5710060208,0.726002637,0.8060434158,0.8534547965,0.8842071579,0.9054773317,0.9209088299]
n = 8

#
# Test logisticfit5() on carefully designed data with a priori known answer.
#
a, b, c, d, g, rep = xalglib.logisticfit5(x, y, n)
print(a) # expected -1.000
print(b) # expected 1.200
print(c) # expected 0.900
print(d) # expected 1.000
print(g) # expected 1.200

#
# Evaluate model at point x=0.5
#
v = xalglib.logisticcalc5(0.5, a, b, c, d, g)
print(v) # expected -0.2354656824

mannwhitneyu module

mannwhitneyutest function

#
# Mann-Whitney U-test
# 
# This test checks hypotheses about whether X  and  Y  are  samples  of  two
# continuous distributions of the same shape  and  same  median  or  whether
# their medians are different.
# 
# The following tests are performed:
#     * two-tailed test (null hypothesis - the medians are equal)
#     * left-tailed test (null hypothesis - the median of the  first  sample
#       is greater than or equal to the median of the second sample)
#     * right-tailed test (null hypothesis - the median of the first  sample
#       is less than or equal to the median of the second sample).
# 
# Requirements:
#     * the samples are independent
#     * X and Y are continuous distributions (or discrete distributions well-
#       approximating continuous distributions)
#     * distributions of X and Y have the  same  shape.  The  only  possible
#       difference is their position (i.e. the value of the median)
#     * the number of elements in each sample is not less than 5
#     * the scale of measurement should be ordinal, interval or ratio  (i.e.
#       the test could not be applied to nominal variables).
# 
# The test is non-parametric and doesn't require distributions to be normal.
# 
# Input parameters:
#     X   -   sample 1. Array whose index goes from 0 to N-1.
#     N   -   size of the sample. N>=5
#     Y   -   sample 2. Array whose index goes from 0 to M-1.
#     M   -   size of the sample. M>=5
# 
# Output parameters:
#     BothTails   -   p-value for two-tailed test.
#                     If BothTails is less than the given significance level
#                     the null hypothesis is rejected.
#     LeftTail    -   p-value for left-tailed test.
#                     If LeftTail is less than the given significance level,
#                     the null hypothesis is rejected.
#     RightTail   -   p-value for right-tailed test.
#                     If RightTail is less than the given significance level
#                     the null hypothesis is rejected.
# 
# To calculate p-values, special approximation is used. This method lets  us
# calculate p-values with satisfactory  accuracy  in  interval  [0.0001, 1].
# There is no approximation outside the [0.0001, 1] interval. Therefore,  if
# the significance level outlies this interval, the test returns 0.0001.
# 
# Relative precision of approximation of p-value:
# 
# N          M          Max.err.   Rms.err.
# 5..10      N..10      1.4e-02    6.0e-04
# 5..10      N..100     2.2e-02    5.3e-06
# 10..15     N..15      1.0e-02    3.2e-04
# 10..15     N..100     1.0e-02    2.2e-05
# 15..100    N..100     6.1e-03    2.7e-06
# 
# For N,M>100 accuracy checks weren't put into  practice,  but  taking  into
# account characteristics of asymptotic approximation used, precision should
# not be sharply different from the values for interval [5, 100].
# 
# NOTE: P-value approximation was  optimized  for  0.0001<=p<=0.2500.  Thus,
#       P's outside of this interval are enforced to these bounds. Say,  you
#       may quite often get P equal to exactly 0.25 or 0.0001.
# 
#   -- ALGLIB --
#      Copyright 09.04.2007 by Bochkanov Sergey
#

SYNTAX: bothtails, lefttail, righttail = xalglib.mannwhitneyutest(x, n, y, m)

matdet module

cmatrixdet function

#
# Calculation of the determinant of a general matrix
# 
# Input parameters:
#     A       -   matrix, array[0..N-1, 0..N-1]
#     N       -   (optional) size of matrix A:
#                 * if given, only principal NxN submatrix is processed and
#                   overwritten. other elements are unchanged.
#                 * if not given, automatically determined from matrix size
#                   (A must be square matrix)
# 
# Result: determinant of matrix A.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: result = xalglib.cmatrixdet(a, n)
SYNTAX: result = xalglib.cmatrixdet(a)

Examples:   [1]  [2]  [3]  

cmatrixludet function

#
# Determinant calculation of the matrix given by its LU decomposition.
# 
# Input parameters:
#     A       -   LU decomposition of the matrix (output of
#                 RMatrixLU subroutine).
#     Pivots  -   table of permutations which were made during
#                 the LU decomposition.
#                 Output of RMatrixLU subroutine.
#     N       -   (optional) size of matrix A:
#                 * if given, only principal NxN submatrix is processed and
#                   overwritten. other elements are unchanged.
#                 * if not given, automatically determined from matrix size
#                   (A must be square matrix)
# 
# Result: matrix determinant.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: result = xalglib.cmatrixludet(a, pivots, n)
SYNTAX: result = xalglib.cmatrixludet(a, pivots)

rmatrixdet function

#
# Calculation of the determinant of a general matrix
# 
# Input parameters:
#     A       -   matrix, array[0..N-1, 0..N-1]
#     N       -   (optional) size of matrix A:
#                 * if given, only principal NxN submatrix is processed and
#                   overwritten. other elements are unchanged.
#                 * if not given, automatically determined from matrix size
#                   (A must be square matrix)
# 
# Result: determinant of matrix A.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: result = xalglib.rmatrixdet(a, n)
SYNTAX: result = xalglib.rmatrixdet(a)

Examples:   [1]  [2]  

rmatrixludet function

#
# Determinant calculation of the matrix given by its LU decomposition.
# 
# Input parameters:
#     A       -   LU decomposition of the matrix (output of
#                 RMatrixLU subroutine).
#     Pivots  -   table of permutations which were made during
#                 the LU decomposition.
#                 Output of RMatrixLU subroutine.
#     N       -   (optional) size of matrix A:
#                 * if given, only principal NxN submatrix is processed and
#                   overwritten. other elements are unchanged.
#                 * if not given, automatically determined from matrix size
#                   (A must be square matrix)
# 
# Result: matrix determinant.
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: result = xalglib.rmatrixludet(a, pivots, n)
SYNTAX: result = xalglib.rmatrixludet(a, pivots)

spdmatrixcholeskydet function

#
# Determinant calculation of the matrix given by the Cholesky decomposition.
# 
# Input parameters:
#     A       -   Cholesky decomposition,
#                 output of SMatrixCholesky subroutine.
#     N       -   (optional) size of matrix A:
#                 * if given, only principal NxN submatrix is processed and
#                   overwritten. other elements are unchanged.
#                 * if not given, automatically determined from matrix size
#                   (A must be square matrix)
# 
# As the determinant is equal to the product of squares of diagonal elements,
# it's not necessary to specify which triangle - lower or upper - the matrix
# is stored in.
# 
# Result:
#     matrix determinant.
# 
#   -- ALGLIB --
#      Copyright 2005-2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.spdmatrixcholeskydet(a, n)
SYNTAX: result = xalglib.spdmatrixcholeskydet(a)

spdmatrixdet function

#
# Determinant calculation of the symmetric positive definite matrix.
# 
# Input parameters:
#     A       -   matrix. Array with elements [0..N-1, 0..N-1].
#     N       -   (optional) size of matrix A:
#                 * if given, only principal NxN submatrix is processed and
#                   overwritten. other elements are unchanged.
#                 * if not given, automatically determined from matrix size
#                   (A must be square matrix)
#     IsUpper -   (optional) storage type:
#                 * if True, symmetric matrix  A  is  given  by  its  upper
#                   triangle, and the lower triangle isn't used/changed  by
#                   function
#                 * if False, symmetric matrix  A  is  given  by  its lower
#                   triangle, and the upper triangle isn't used/changed  by
#                   function
#                 * if not given, both lower and upper  triangles  must  be
#                   filled.
# 
# Result:
#     determinant of matrix A.
#     If matrix A is not positive definite, exception is thrown.
# 
#   -- ALGLIB --
#      Copyright 2005-2008 by Bochkanov Sergey
#

SYNTAX: result = xalglib.spdmatrixdet(a, n, isupper)
SYNTAX: result = xalglib.spdmatrixdet(a)

matdet_d_1 example

import xalglib



b = [[1,2],[2,1]]
a = xalglib.rmatrixdet(b)
print(a) # expected -3

matdet_d_2 example

import xalglib



b = [[5,4],[4,5]]
a = xalglib.rmatrixdet(b, 2)
print(a) # expected 9

matdet_d_3 example

import xalglib



b = [[1+1j,2],[2,1-1j]]
a = xalglib.cmatrixdet(b)
print(a) # expected -2

matdet_d_4 example

import xalglib



b = [[5j,4],[4j,5]]
a = xalglib.cmatrixdet(b, 2)
print(a) # expected 9j

matdet_d_5 example

import xalglib



b = [[9,1],[2,1]]
a = xalglib.cmatrixdet(b)
print(a) # expected 7

matgen module

cmatrixrndcond function

#
# Generation of random NxN complex matrix with given condition number C and
# norm2(A)=1
# 
# INPUT PARAMETERS:
#     N   -   matrix size
#     C   -   condition number (in 2-norm)
# 
# OUTPUT PARAMETERS:
#     A   -   random matrix with norm2(A)=1 and cond(A)=C
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.cmatrixrndcond(n, c)

cmatrixrndorthogonal function

#
# Generation of a random Haar distributed orthogonal complex matrix
# 
# INPUT PARAMETERS:
#     N   -   matrix size, N>=1
# 
# OUTPUT PARAMETERS:
#     A   -   orthogonal NxN matrix, array[0..N-1,0..N-1]
# 
# NOTE: this function uses algorithm  described  in  Stewart, G. W.  (1980),
#       "The Efficient Generation of  Random  Orthogonal  Matrices  with  an
#       Application to Condition Estimators".
# 
#       Speaking short, to generate an (N+1)x(N+1) orthogonal matrix, it:
#       * takes an NxN one
#       * takes uniformly distributed unit vector of dimension N+1.
#       * constructs a Householder reflection from the vector, then applies
#         it to the smaller matrix (embedded in the larger size with a 1 at
#         the bottom right corner).
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.cmatrixrndorthogonal(n)

cmatrixrndorthogonalfromtheleft function

#
# Multiplication of MxN complex matrix by MxM random Haar distributed
# complex orthogonal matrix
# 
# INPUT PARAMETERS:
#     A   -   matrix, array[0..M-1, 0..N-1]
#     M, N-   matrix size
# 
# OUTPUT PARAMETERS:
#     A   -   Q*A, where Q is random MxM orthogonal matrix
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.cmatrixrndorthogonalfromtheleft(a, m, n)

cmatrixrndorthogonalfromtheright function

#
# Multiplication of MxN complex matrix by NxN random Haar distributed
# complex orthogonal matrix
# 
# INPUT PARAMETERS:
#     A   -   matrix, array[0..M-1, 0..N-1]
#     M, N-   matrix size
# 
# OUTPUT PARAMETERS:
#     A   -   A*Q, where Q is random NxN orthogonal matrix
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.cmatrixrndorthogonalfromtheright(a, m, n)

hmatrixrndcond function

#
# Generation of random NxN Hermitian matrix with given condition number  and
# norm2(A)=1
# 
# INPUT PARAMETERS:
#     N   -   matrix size
#     C   -   condition number (in 2-norm)
# 
# OUTPUT PARAMETERS:
#     A   -   random matrix with norm2(A)=1 and cond(A)=C
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.hmatrixrndcond(n, c)

hmatrixrndmultiply function

#
# Hermitian multiplication of NxN matrix by random Haar distributed
# complex orthogonal matrix
# 
# INPUT PARAMETERS:
#     A   -   matrix, array[0..N-1, 0..N-1]
#     N   -   matrix size
# 
# OUTPUT PARAMETERS:
#     A   -   Q^H*A*Q, where Q is random NxN orthogonal matrix
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.hmatrixrndmultiply(a, n)

hpdmatrixrndcond function

#
# Generation of random NxN Hermitian positive definite matrix with given
# condition number and norm2(A)=1
# 
# INPUT PARAMETERS:
#     N   -   matrix size
#     C   -   condition number (in 2-norm)
# 
# OUTPUT PARAMETERS:
#     A   -   random HPD matrix with norm2(A)=1 and cond(A)=C
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.hpdmatrixrndcond(n, c)

rmatrixrndcond function

#
# Generation of random NxN matrix with given condition number and norm2(A)=1
# 
# INPUT PARAMETERS:
#     N   -   matrix size
#     C   -   condition number (in 2-norm)
# 
# OUTPUT PARAMETERS:
#     A   -   random matrix with norm2(A)=1 and cond(A)=C
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.rmatrixrndcond(n, c)

rmatrixrndorthogonal function

#
# Generation of a random uniformly distributed (Haar) orthogonal matrix
# 
# INPUT PARAMETERS:
#     N   -   matrix size, N>=1
# 
# OUTPUT PARAMETERS:
#     A   -   orthogonal NxN matrix, array[0..N-1,0..N-1]
# 
# NOTE: this function uses algorithm  described  in  Stewart, G. W.  (1980),
#       "The Efficient Generation of  Random  Orthogonal  Matrices  with  an
#       Application to Condition Estimators".
# 
#       Speaking short, to generate an (N+1)x(N+1) orthogonal matrix, it:
#       * takes an NxN one
#       * takes uniformly distributed unit vector of dimension N+1.
#       * constructs a Householder reflection from the vector, then applies
#         it to the smaller matrix (embedded in the larger size with a 1 at
#         the bottom right corner).
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.rmatrixrndorthogonal(n)

rmatrixrndorthogonalfromtheleft function

#
# Multiplication of MxN matrix by MxM random Haar distributed orthogonal matrix
# 
# INPUT PARAMETERS:
#     A   -   matrix, array[0..M-1, 0..N-1]
#     M, N-   matrix size
# 
# OUTPUT PARAMETERS:
#     A   -   Q*A, where Q is random MxM orthogonal matrix
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.rmatrixrndorthogonalfromtheleft(a, m, n)

rmatrixrndorthogonalfromtheright function

#
# Multiplication of MxN matrix by NxN random Haar distributed orthogonal matrix
# 
# INPUT PARAMETERS:
#     A   -   matrix, array[0..M-1, 0..N-1]
#     M, N-   matrix size
# 
# OUTPUT PARAMETERS:
#     A   -   A*Q, where Q is random NxN orthogonal matrix
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.rmatrixrndorthogonalfromtheright(a, m, n)

smatrixrndcond function

#
# Generation of random NxN symmetric matrix with given condition number  and
# norm2(A)=1
# 
# INPUT PARAMETERS:
#     N   -   matrix size
#     C   -   condition number (in 2-norm)
# 
# OUTPUT PARAMETERS:
#     A   -   random matrix with norm2(A)=1 and cond(A)=C
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.smatrixrndcond(n, c)

smatrixrndmultiply function

#
# Symmetric multiplication of NxN matrix by random Haar distributed
# orthogonal  matrix
# 
# INPUT PARAMETERS:
#     A   -   matrix, array[0..N-1, 0..N-1]
#     N   -   matrix size
# 
# OUTPUT PARAMETERS:
#     A   -   Q'*A*Q, where Q is random NxN orthogonal matrix
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.smatrixrndmultiply(a, n)

spdmatrixrndcond function

#
# Generation of random NxN symmetric positive definite matrix with given
# condition number and norm2(A)=1
# 
# INPUT PARAMETERS:
#     N   -   matrix size
#     C   -   condition number (in 2-norm)
# 
# OUTPUT PARAMETERS:
#     A   -   random SPD matrix with norm2(A)=1 and cond(A)=C
# 
#   -- ALGLIB routine --
#      04.12.2009
#      Bochkanov Sergey
#

SYNTAX: a = xalglib.spdmatrixrndcond(n, c)

matinv module

matinvreport class

#
# Matrix inverse report:
# * R1    reciprocal of condition number in 1-norm
# * RInf  reciprocal of condition number in inf-norm
#

class matinvreport(object):
    ...

cmatrixinverse function

#
# Inversion of a general matrix.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that matrix inversion  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   matrix
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
# 
# Output parameters:
#     Info    -   return code, same as in RMatrixLUInverse
#     Rep     -   solver report, same as in RMatrixLUInverse
#     A       -   inverse of matrix A, same as in RMatrixLUInverse
# 
#   -- ALGLIB --
#      Copyright 2005 by Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.cmatrixinverse(a, n)
SYNTAX: a, info, rep = xalglib.cmatrixinverse(a)
SYNTAX: a, info, rep = xalglib.smp_cmatrixinverse(a, n)
SYNTAX: a, info, rep = xalglib.smp_cmatrixinverse(a)

Examples:   [1]  

cmatrixluinverse function

#
# Inversion of a matrix given by its LU decomposition.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that matrix inversion  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     A       -   LU decomposition of the matrix
#                 (output of CMatrixLU subroutine).
#     Pivots  -   table of permutations
#                 (the output of CMatrixLU subroutine).
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
# 
# OUTPUT PARAMETERS:
#     Info    -   return code, same as in RMatrixLUInverse
#     Rep     -   solver report, same as in RMatrixLUInverse
#     A       -   inverse of matrix A, same as in RMatrixLUInverse
# 
#   -- ALGLIB routine --
#      05.02.2010
#      Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.cmatrixluinverse(a, pivots, n)
SYNTAX: a, info, rep = xalglib.cmatrixluinverse(a, pivots)
SYNTAX: a, info, rep = xalglib.smp_cmatrixluinverse(a, pivots, n)
SYNTAX: a, info, rep = xalglib.smp_cmatrixluinverse(a, pivots)

cmatrixtrinverse function

#
# Triangular matrix inverse (complex)
# 
# The subroutine inverts the following types of matrices:
#     * upper triangular
#     * upper triangular with unit diagonal
#     * lower triangular
#     * lower triangular with unit diagonal
# 
# In case of an upper (lower) triangular matrix,  the  inverse  matrix  will
# also be upper (lower) triangular, and after the end of the algorithm,  the
# inverse matrix replaces the source matrix. The elements  below (above) the
# main diagonal are not changed by the algorithm.
# 
# If  the matrix  has a unit diagonal, the inverse matrix also  has  a  unit
# diagonal, and the diagonal elements are not passed to the algorithm.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that triangular inverse is harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   matrix, array[0..N-1, 0..N-1].
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
#     IsUpper -   True, if the matrix is upper triangular.
#     IsUnit  -   diagonal type (optional):
#                 * if True, matrix has unit diagonal (a[i,i] are NOT used)
#                 * if False, matrix diagonal is arbitrary
#                 * if not given, False is assumed
# 
# Output parameters:
#     Info    -   same as for RMatrixLUInverse
#     Rep     -   same as for RMatrixLUInverse
#     A       -   same as for RMatrixLUInverse.
# 
#   -- ALGLIB --
#      Copyright 05.02.2010 by Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.cmatrixtrinverse(a, n, isupper, isunit)
SYNTAX: a, info, rep = xalglib.cmatrixtrinverse(a, isupper)
SYNTAX: a, info, rep = xalglib.smp_cmatrixtrinverse(a, n, isupper, isunit)
SYNTAX: a, info, rep = xalglib.smp_cmatrixtrinverse(a, isupper)

hpdmatrixcholeskyinverse function

#
# Inversion of a Hermitian positive definite matrix which is given
# by Cholesky decomposition.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  However,  Cholesky  inversion  is  a  "difficult"
#   ! algorithm  -  it  has  lots  of  internal synchronization points which
#   ! prevents efficient  parallelization  of  algorithm.  Only  very  large
#   ! problems (N=thousands) can be efficiently parallelized.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   Cholesky decomposition of the matrix to be inverted:
#                 A=U'*U or A = L*L'.
#                 Output of  HPDMatrixCholesky subroutine.
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
#     IsUpper -   storage type (optional):
#                 * if True, symmetric  matrix  A  is  given  by  its  upper
#                   triangle, and the lower triangle isn't  used/changed  by
#                   function
#                 * if False,  symmetric matrix  A  is  given  by  its lower
#                   triangle, and the  upper triangle isn't used/changed  by
#                   function
#                 * if not given, lower half is used.
# 
# Output parameters:
#     Info    -   return code, same as in RMatrixLUInverse
#     Rep     -   solver report, same as in RMatrixLUInverse
#     A       -   inverse of matrix A, same as in RMatrixLUInverse
# 
#   -- ALGLIB routine --
#      10.02.2010
#      Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.hpdmatrixcholeskyinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.hpdmatrixcholeskyinverse(a)
SYNTAX: a, info, rep = xalglib.smp_hpdmatrixcholeskyinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.smp_hpdmatrixcholeskyinverse(a)

hpdmatrixinverse function

#
# Inversion of a Hermitian positive definite matrix.
# 
# Given an upper or lower triangle of a Hermitian positive definite matrix,
# the algorithm generates matrix A^-1 and saves the upper or lower triangle
# depending on the input.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  However,  Cholesky  inversion  is  a  "difficult"
#   ! algorithm  -  it  has  lots  of  internal synchronization points which
#   ! prevents efficient  parallelization  of  algorithm.  Only  very  large
#   ! problems (N=thousands) can be efficiently parallelized.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   matrix to be inverted (upper or lower triangle).
#                 Array with elements [0..N-1,0..N-1].
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
#     IsUpper -   storage type (optional):
#                 * if True, symmetric  matrix  A  is  given  by  its  upper
#                   triangle, and the lower triangle isn't  used/changed  by
#                   function
#                 * if False,  symmetric matrix  A  is  given  by  its lower
#                   triangle, and the  upper triangle isn't used/changed  by
#                   function
#                 * if not given,  both lower and upper  triangles  must  be
#                   filled.
# 
# Output parameters:
#     Info    -   return code, same as in RMatrixLUInverse
#     Rep     -   solver report, same as in RMatrixLUInverse
#     A       -   inverse of matrix A, same as in RMatrixLUInverse
# 
#   -- ALGLIB routine --
#      10.02.2010
#      Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.hpdmatrixinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.hpdmatrixinverse(a)
SYNTAX: a, info, rep = xalglib.smp_hpdmatrixinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.smp_hpdmatrixinverse(a)

Examples:   [1]  

rmatrixinverse function

#
# Inversion of a general matrix.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that matrix inversion  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   matrix.
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
# 
# Output parameters:
#     Info    -   return code, same as in RMatrixLUInverse
#     Rep     -   solver report, same as in RMatrixLUInverse
#     A       -   inverse of matrix A, same as in RMatrixLUInverse
# 
# Result:
#     True, if the matrix is not singular.
#     False, if the matrix is singular.
# 
#   -- ALGLIB --
#      Copyright 2005-2010 by Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.rmatrixinverse(a, n)
SYNTAX: a, info, rep = xalglib.rmatrixinverse(a)
SYNTAX: a, info, rep = xalglib.smp_rmatrixinverse(a, n)
SYNTAX: a, info, rep = xalglib.smp_rmatrixinverse(a)

Examples:   [1]  

rmatrixluinverse function

#
# Inversion of a matrix given by its LU decomposition.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that matrix inversion  is  harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# INPUT PARAMETERS:
#     A       -   LU decomposition of the matrix
#                 (output of RMatrixLU subroutine).
#     Pivots  -   table of permutations
#                 (the output of RMatrixLU subroutine).
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
# 
# OUTPUT PARAMETERS:
#     Info    -   return code:
#                 * -3    A is singular, or VERY close to singular.
#                         it is filled by zeros in such cases.
#                 *  1    task is solved (but matrix A may be ill-conditioned,
#                         check R1/RInf parameters for condition numbers).
#     Rep     -   solver report, see below for more info
#     A       -   inverse of matrix A.
#                 Array whose indexes range within [0..N-1, 0..N-1].
# 
# SOLVER REPORT
# 
# Subroutine sets following fields of the Rep structure:
# * R1        reciprocal of condition number: 1/cond(A), 1-norm.
# * RInf      reciprocal of condition number: 1/cond(A), inf-norm.
# 
#   -- ALGLIB routine --
#      05.02.2010
#      Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.rmatrixluinverse(a, pivots, n)
SYNTAX: a, info, rep = xalglib.rmatrixluinverse(a, pivots)
SYNTAX: a, info, rep = xalglib.smp_rmatrixluinverse(a, pivots, n)
SYNTAX: a, info, rep = xalglib.smp_rmatrixluinverse(a, pivots)

rmatrixtrinverse function

#
# Triangular matrix inverse (real)
# 
# The subroutine inverts the following types of matrices:
#     * upper triangular
#     * upper triangular with unit diagonal
#     * lower triangular
#     * lower triangular with unit diagonal
# 
# In case of an upper (lower) triangular matrix,  the  inverse  matrix  will
# also be upper (lower) triangular, and after the end of the algorithm,  the
# inverse matrix replaces the source matrix. The elements  below (above) the
# main diagonal are not changed by the algorithm.
# 
# If  the matrix  has a unit diagonal, the inverse matrix also  has  a  unit
# diagonal, and the diagonal elements are not passed to the algorithm.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of this function. We should note that triangular inverse is harder  to
#   ! parallelize than, say, matrix-matrix  product  -  this  algorithm  has
#   ! many internal synchronization points which can not be avoided. However
#   ! parallelism starts to be profitable starting  from  N=1024,  achieving
#   ! near-linear speedup for N=4096 or higher.
#   !
#   ! In order to use multicore features you have to:
#   ! * use commercial version of ALGLIB
#   ! * call  this  function  with  "smp_"  prefix,  which  indicates  that
#   !   multicore code will be used (for multicore support)
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   matrix, array[0..N-1, 0..N-1].
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
#     IsUpper -   True, if the matrix is upper triangular.
#     IsUnit  -   diagonal type (optional):
#                 * if True, matrix has unit diagonal (a[i,i] are NOT used)
#                 * if False, matrix diagonal is arbitrary
#                 * if not given, False is assumed
# 
# Output parameters:
#     Info    -   same as for RMatrixLUInverse
#     Rep     -   same as for RMatrixLUInverse
#     A       -   same as for RMatrixLUInverse.
# 
#   -- ALGLIB --
#      Copyright 05.02.2010 by Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.rmatrixtrinverse(a, n, isupper, isunit)
SYNTAX: a, info, rep = xalglib.rmatrixtrinverse(a, isupper)
SYNTAX: a, info, rep = xalglib.smp_rmatrixtrinverse(a, n, isupper, isunit)
SYNTAX: a, info, rep = xalglib.smp_rmatrixtrinverse(a, isupper)

spdmatrixcholeskyinverse function

#
# Inversion of a symmetric positive definite matrix which is given
# by Cholesky decomposition.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  However,  Cholesky  inversion  is  a  "difficult"
#   ! algorithm  -  it  has  lots  of  internal synchronization points which
#   ! prevents efficient  parallelization  of  algorithm.  Only  very  large
#   ! problems (N=thousands) can be efficiently parallelized.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   Cholesky decomposition of the matrix to be inverted:
#                 A=U'*U or A = L*L'.
#                 Output of  SPDMatrixCholesky subroutine.
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
#     IsUpper -   storage type (optional):
#                 * if True, symmetric  matrix  A  is  given  by  its  upper
#                   triangle, and the lower triangle isn't  used/changed  by
#                   function
#                 * if False,  symmetric matrix  A  is  given  by  its lower
#                   triangle, and the  upper triangle isn't used/changed  by
#                   function
#                 * if not given, lower half is used.
# 
# Output parameters:
#     Info    -   return code, same as in RMatrixLUInverse
#     Rep     -   solver report, same as in RMatrixLUInverse
#     A       -   inverse of matrix A, same as in RMatrixLUInverse
# 
#   -- ALGLIB routine --
#      10.02.2010
#      Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.spdmatrixcholeskyinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.spdmatrixcholeskyinverse(a)
SYNTAX: a, info, rep = xalglib.smp_spdmatrixcholeskyinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.smp_spdmatrixcholeskyinverse(a)

spdmatrixinverse function

#
# Inversion of a symmetric positive definite matrix.
# 
# Given an upper or lower triangle of a symmetric positive definite matrix,
# the algorithm generates matrix A^-1 and saves the upper or lower triangle
# depending on the input.
# 
# COMMERCIAL EDITION OF ALGLIB:
# 
#   ! Commercial version of ALGLIB includes two  important  improvements  of
#   ! this function, which can be used from C++ and C#:
#   ! * Intel MKL support (lightweight Intel MKL is shipped with ALGLIB)
#   ! * multicore support
#   !
#   ! Intel MKL gives approximately constant  (with  respect  to  number  of
#   ! worker threads) acceleration factor which depends on CPU  being  used,
#   ! problem  size  and  "baseline"  ALGLIB  edition  which  is  used   for
#   ! comparison.
#   !
#   ! Say, on SSE2-capable CPU with N=1024, HPC ALGLIB will be:
#   ! * about 2-3x faster than ALGLIB for C++ without MKL
#   ! * about 7-10x faster than "pure C#" edition of ALGLIB
#   ! Difference in performance will be more striking  on  newer  CPU's with
#   ! support for newer SIMD instructions. Generally,  MKL  accelerates  any
#   ! problem whose size is at least 128, with best  efficiency achieved for
#   ! N's larger than 512.
#   !
#   ! Commercial edition of ALGLIB also supports multithreaded  acceleration
#   ! of  this  function.  However,  Cholesky  inversion  is  a  "difficult"
#   ! algorithm  -  it  has  lots  of  internal synchronization points which
#   ! prevents efficient  parallelization  of  algorithm.  Only  very  large
#   ! problems (N=thousands) can be efficiently parallelized.
#   !
#   ! We recommend you to read 'Working with commercial version' section  of
#   ! ALGLIB Reference Manual in order to find out how to  use  performance-
#   ! related features provided by commercial edition of ALGLIB.
# 
# Input parameters:
#     A       -   matrix to be inverted (upper or lower triangle).
#                 Array with elements [0..N-1,0..N-1].
#     N       -   size of matrix A (optional) :
#                 * if given, only principal NxN submatrix is processed  and
#                   overwritten. other elements are unchanged.
#                 * if not given,  size  is  automatically  determined  from
#                   matrix size (A must be square matrix)
#     IsUpper -   storage type (optional):
#                 * if True, symmetric  matrix  A  is  given  by  its  upper
#                   triangle, and the lower triangle isn't  used/changed  by
#                   function
#                 * if False,  symmetric matrix  A  is  given  by  its lower
#                   triangle, and the  upper triangle isn't used/changed  by
#                   function
#                 * if not given,  both lower and upper  triangles  must  be
#                   filled.
# 
# Output parameters:
#     Info    -   return code, same as in RMatrixLUInverse
#     Rep     -   solver report, same as in RMatrixLUInverse
#     A       -   inverse of matrix A, same as in RMatrixLUInverse
# 
#   -- ALGLIB routine --
#      10.02.2010
#      Bochkanov Sergey
#

SYNTAX: a, info, rep = xalglib.spdmatrixinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.spdmatrixinverse(a)
SYNTAX: a, info, rep = xalglib.smp_spdmatrixinverse(a, n, isupper)
SYNTAX: a, info, rep = xalglib.smp_spdmatrixinverse(a)

Examples:   [1]  

matinv_d_c1 example

import xalglib



a = [[1j,-1],[1j,1]]
a, info, rep = xalglib.cmatrixinverse(a)
print(info) # expected 1
print(a) # expected [[-0.5j,-0.5j],[-0.5,0.5]]
print(rep.r1) # expected 0.5
print(rep.rinf) # expected 0.5

matinv_d_hpd1 example

import xalglib



a = [[2,1],[1,2]]
a, info, rep = xalglib.hpdmatrixinverse(a)
print(info) # expected 1
print(a) # expected [[0.666666,-0.333333],[-0.333333,0.666666]]

matinv_d_r1 example

import xalglib



a = [[1,-1],[1,1]]
a, info, rep = xalglib.rmatrixinverse(a)
print(info) # expected 1
print(a) # expected [[0.5,0.5],[-0.5,0.5]]
print(rep.r1) # expected 0.5
print(rep.rinf) # expected 0.5

matinv_d_spd1 example

import xalglib



a = [[2,1],[1,2]]
a, info, rep = xalglib.spdmatrixinverse(a)
print(info) # expected 1
print(a) # expected [[0.666666,-0.333333],[-0.333333,0.666666]]

mcpd module

mcpdreport class

#
# This structure is a MCPD training report:
#     InnerIterationsCount    -   number of inner iterations of the
#                                 underlying optimization algorithm
#     OuterIterationsCount    -   number of outer iterations of the
#                                 underlying optimization algorithm
#     NFEV                    -   number of merit function evaluations
#     TerminationType         -   termination type
#                                 (same as for MinBLEIC optimizer, positive
#                                 values denote success, negative ones -
#                                 failure)
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

class mcpdreport(object):
    ...

mcpdstate class

#
# This structure is a MCPD (Markov Chains for Population Data) solver.
# 
# You should use ALGLIB functions in order to work with this object.
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

class mcpdstate(object):
    ...

mcpdaddbc function

#
# This function is used to add bound constraints  on  the  elements  of  the
# transition matrix P.
# 
# MCPD solver has four types of constraints which can be placed on P:
# * user-specified equality constraints (optional)
# * user-specified bound constraints (optional)
# * user-specified general linear constraints (optional)
# * basic constraints (always present):
#   * non-negativity: P[i,j]>=0
#   * consistency: every column of P sums to 1.0
# 
# Final  constraints  which  are  passed  to  the  underlying  optimizer are
# calculated  as  intersection  of all present constraints. For example, you
# may specify boundary constraint on P[0,0] and equality one:
#     0.1<=P[0,0]<=0.9
#     P[0,0]=0.5
# Such  combination  of  constraints  will  be  silently  reduced  to  their
# intersection, which is P[0,0]=0.5.
# 
# This  function  can  be  used to ADD bound constraint for one element of P
# without changing constraints for other elements.
# 
# You  can  also  use  MCPDSetBC()  function  which  allows to  place  bound
# constraints  on arbitrary subset of elements of P.   Set of constraints is
# specified  by  BndL/BndU matrices, which may contain arbitrary combination
# of finite numbers or infinities (like -INF<x<=0.5 or 0.1<=x<+INF).
# 
# These functions (MCPDSetBC and MCPDAddBC) interact as follows:
# * there is internal matrix of bound constraints which is stored in the
#   MCPD solver
# * MCPDSetBC() replaces this matrix by another one (SET)
# * MCPDAddBC() modifies one element of this matrix and  leaves  other  ones
#   unchanged (ADD)
# * thus  MCPDAddBC()  call  preserves  all  modifications  done by previous
#   calls,  while  MCPDSetBC()  completely discards all changes  done to the
#   equality constraints.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     I       -   row index of element being constrained
#     J       -   column index of element being constrained
#     BndL    -   lower bound
#     BndU    -   upper bound
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdaddbc(s, i, j, bndl, bndu)

mcpdaddec function

#
# This function is used to add equality constraints on the elements  of  the
# transition matrix P.
# 
# MCPD solver has four types of constraints which can be placed on P:
# * user-specified equality constraints (optional)
# * user-specified bound constraints (optional)
# * user-specified general linear constraints (optional)
# * basic constraints (always present):
#   * non-negativity: P[i,j]>=0
#   * consistency: every column of P sums to 1.0
# 
# Final  constraints  which  are  passed  to  the  underlying  optimizer are
# calculated  as  intersection  of all present constraints. For example, you
# may specify boundary constraint on P[0,0] and equality one:
#     0.1<=P[0,0]<=0.9
#     P[0,0]=0.5
# Such  combination  of  constraints  will  be  silently  reduced  to  their
# intersection, which is P[0,0]=0.5.
# 
# This function can be used to ADD equality constraint for one element of  P
# without changing constraints for other elements.
# 
# You  can  also  use  MCPDSetEC()  function  which  allows  you  to specify
# arbitrary set of equality constraints in one call.
# 
# These functions (MCPDSetEC and MCPDAddEC) interact as follows:
# * there is internal matrix of equality constraints which is stored in the
#   MCPD solver
# * MCPDSetEC() replaces this matrix by another one (SET)
# * MCPDAddEC() modifies one element of this matrix and leaves  other  ones
#   unchanged (ADD)
# * thus  MCPDAddEC()  call  preserves  all  modifications done by previous
#   calls,  while  MCPDSetEC()  completely discards all changes done to the
#   equality constraints.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     I       -   row index of element being constrained
#     J       -   column index of element being constrained
#     C       -   value (constraint for P[I,J]).  Can  be  either  NAN  (no
#                 constraint) or finite value from [0,1].
# 
# NOTES:
# 
# 1. infinite values of C  will lead to exception being thrown. Values  less
# than 0.0 or greater than 1.0 will lead to error code being returned  after
# call to MCPDSolve().
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdaddec(s, i, j, c)

Examples:   [1]  

mcpdaddtrack function

#
# This  function  is  used to add a track - sequence of system states at the
# different moments of its evolution.
# 
# You  may  add  one  or several tracks to the MCPD solver. In case you have
# several tracks, they won't overwrite each other. For example,  if you pass
# two tracks, A1-A2-A3 (system at t=A+1, t=A+2 and t=A+3) and B1-B2-B3, then
# solver will try to model transitions from t=A+1 to t=A+2, t=A+2 to  t=A+3,
# t=B+1 to t=B+2, t=B+2 to t=B+3. But it WONT mix these two tracks - i.e. it
# wont try to model transition from t=A+3 to t=B+1.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     XY      -   track, array[K,N]:
#                 * I-th row is a state at t=I
#                 * elements of XY must be non-negative (exception will be
#                   thrown on negative elements)
#     K       -   number of points in a track
#                 * if given, only leading K rows of XY are used
#                 * if not given, automatically determined from size of XY
# 
# NOTES:
# 
# 1. Track may contain either proportional or population data:
#    * with proportional data all rows of XY must sum to 1.0, i.e. we have
#      proportions instead of absolute population values
#    * with population data rows of XY contain population counts and generally
#      do not sum to 1.0 (although they still must be non-negative)
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdaddtrack(s, xy, k)
SYNTAX: xalglib.mcpdaddtrack(s, xy)

Examples:   [1]  [2]  

mcpdcreate function

#
# DESCRIPTION:
# 
# This function creates MCPD (Markov Chains for Population Data) solver.
# 
# This  solver  can  be  used  to find transition matrix P for N-dimensional
# prediction  problem  where transition from X[i] to X[i+1] is  modelled  as
#     X[i+1] = P*X[i]
# where X[i] and X[i+1] are N-dimensional population vectors (components  of
# each X are non-negative), and P is a N*N transition matrix (elements of  P
# are non-negative, each column sums to 1.0).
# 
# Such models arise when when:
# * there is some population of individuals
# * individuals can have different states
# * individuals can transit from one state to another
# * population size is constant, i.e. there is no new individuals and no one
#   leaves population
# * you want to model transitions of individuals from one state into another
# 
# USAGE:
# 
# Here we give very brief outline of the MCPD. We strongly recommend you  to
# read examples in the ALGLIB Reference Manual and to read ALGLIB User Guide
# on data analysis which is available at http://www.alglib.net/dataanalysis/
# 
# 1. User initializes algorithm state with MCPDCreate() call
# 
# 2. User  adds  one  or  more  tracks -  sequences of states which describe
#    evolution of a system being modelled from different starting conditions
# 
# 3. User may add optional boundary, equality  and/or  linear constraints on
#    the coefficients of P by calling one of the following functions:
#    * MCPDSetEC() to set equality constraints
#    * MCPDSetBC() to set bound constraints
#    * MCPDSetLC() to set linear constraints
# 
# 4. Optionally,  user  may  set  custom  weights  for prediction errors (by
#    default, algorithm assigns non-equal, automatically chosen weights  for
#    errors in the prediction of different components of X). It can be  done
#    with a call of MCPDSetPredictionWeights() function.
# 
# 5. User calls MCPDSolve() function which takes algorithm  state and
#    pointer (delegate, etc.) to callback function which calculates F/G.
# 
# 6. User calls MCPDResults() to get solution
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>=1
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: s = xalglib.mcpdcreate(n)

Examples:   [1]  [2]  

mcpdcreateentry function

#
# DESCRIPTION:
# 
# This function is a specialized version of MCPDCreate()  function,  and  we
# recommend  you  to read comments for this function for general information
# about MCPD solver.
# 
# This  function  creates  MCPD (Markov Chains for Population  Data)  solver
# for "Entry-state" model,  i.e. model  where transition from X[i] to X[i+1]
# is modelled as
#     X[i+1] = P*X[i]
# where
#     X[i] and X[i+1] are N-dimensional state vectors
#     P is a N*N transition matrix
# and  one  selected component of X[] is called "entry" state and is treated
# in a special way:
#     system state always transits from "entry" state to some another state
#     system state can not transit from any state into "entry" state
# Such conditions basically mean that row of P which corresponds to  "entry"
# state is zero.
# 
# Such models arise when:
# * there is some population of individuals
# * individuals can have different states
# * individuals can transit from one state to another
# * population size is NOT constant -  at every moment of time there is some
#   (unpredictable) amount of "new" individuals, which can transit into  one
#   of the states at the next turn, but still no one leaves population
# * you want to model transitions of individuals from one state into another
# * but you do NOT want to predict amount of "new"  individuals  because  it
#   does not depends on individuals already present (hence  system  can  not
#   transit INTO entry state - it can only transit FROM it).
# 
# This model is discussed  in  more  details  in  the ALGLIB User Guide (see
# http://www.alglib.net/dataanalysis/ for more data).
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>=2
#     EntryState- index of entry state, in 0..N-1
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: s = xalglib.mcpdcreateentry(n, entrystate)

mcpdcreateentryexit function

#
# DESCRIPTION:
# 
# This function is a specialized version of MCPDCreate()  function,  and  we
# recommend  you  to read comments for this function for general information
# about MCPD solver.
# 
# This  function  creates  MCPD (Markov Chains for Population  Data)  solver
# for "Entry-Exit-states" model, i.e. model where  transition  from  X[i] to
# X[i+1] is modelled as
#     X[i+1] = P*X[i]
# where
#     X[i] and X[i+1] are N-dimensional state vectors
#     P is a N*N transition matrix
# one selected component of X[] is called "entry" state and is treated in  a
# special way:
#     system state always transits from "entry" state to some another state
#     system state can not transit from any state into "entry" state
# and another one component of X[] is called "exit" state and is treated  in
# a special way too:
#     system state can transit from any state into "exit" state
#     system state can not transit from "exit" state into any other state
#     transition operator discards "exit" state (makes it zero at each turn)
# Such conditions basically mean that:
#     row of P which corresponds to "entry" state is zero
#     column of P which corresponds to "exit" state is zero
# Multiplication by such P may decrease sum of vector components.
# 
# Such models arise when:
# * there is some population of individuals
# * individuals can have different states
# * individuals can transit from one state to another
# * population size is NOT constant
# * at every moment of time there is some (unpredictable)  amount  of  "new"
#   individuals, which can transit into one of the states at the next turn
# * some  individuals  can  move  (predictably)  into "exit" state and leave
#   population at the next turn
# * you want to model transitions of individuals from one state into another,
#   including transitions from the "entry" state and into the "exit" state.
# * but you do NOT want to predict amount of "new"  individuals  because  it
#   does not depends on individuals already present (hence  system  can  not
#   transit INTO entry state - it can only transit FROM it).
# 
# This model is discussed  in  more  details  in  the ALGLIB User Guide (see
# http://www.alglib.net/dataanalysis/ for more data).
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>=2
#     EntryState- index of entry state, in 0..N-1
#     ExitState-  index of exit state, in 0..N-1
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: s = xalglib.mcpdcreateentryexit(n, entrystate, exitstate)

mcpdcreateexit function

#
# DESCRIPTION:
# 
# This function is a specialized version of MCPDCreate()  function,  and  we
# recommend  you  to read comments for this function for general information
# about MCPD solver.
# 
# This  function  creates  MCPD (Markov Chains for Population  Data)  solver
# for "Exit-state" model,  i.e. model  where  transition from X[i] to X[i+1]
# is modelled as
#     X[i+1] = P*X[i]
# where
#     X[i] and X[i+1] are N-dimensional state vectors
#     P is a N*N transition matrix
# and  one  selected component of X[] is called "exit"  state and is treated
# in a special way:
#     system state can transit from any state into "exit" state
#     system state can not transit from "exit" state into any other state
#     transition operator discards "exit" state (makes it zero at each turn)
# Such  conditions  basically  mean  that  column  of P which corresponds to
# "exit" state is zero. Multiplication by such P may decrease sum of  vector
# components.
# 
# Such models arise when:
# * there is some population of individuals
# * individuals can have different states
# * individuals can transit from one state to another
# * population size is NOT constant - individuals can move into "exit" state
#   and leave population at the next turn, but there are no new individuals
# * amount of individuals which leave population can be predicted
# * you want to model transitions of individuals from one state into another
#   (including transitions into the "exit" state)
# 
# This model is discussed  in  more  details  in  the ALGLIB User Guide (see
# http://www.alglib.net/dataanalysis/ for more data).
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>=2
#     ExitState-  index of exit state, in 0..N-1
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: s = xalglib.mcpdcreateexit(n, exitstate)

mcpdresults function

#
# MCPD results
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     P       -   array[N,N], transition matrix
#     Rep     -   optimization report. You should check Rep.TerminationType
#                 in  order  to  distinguish  successful  termination  from
#                 unsuccessful one. Speaking short, positive values  denote
#                 success, negative ones are failures.
#                 More information about fields of this  structure  can  be
#                 found in the comments on MCPDReport datatype.
# 
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: p, rep = xalglib.mcpdresults(s)

Examples:   [1]  [2]  

mcpdsetbc function

#
# This function is used to add bound constraints  on  the  elements  of  the
# transition matrix P.
# 
# MCPD solver has four types of constraints which can be placed on P:
# * user-specified equality constraints (optional)
# * user-specified bound constraints (optional)
# * user-specified general linear constraints (optional)
# * basic constraints (always present):
#   * non-negativity: P[i,j]>=0
#   * consistency: every column of P sums to 1.0
# 
# Final  constraints  which  are  passed  to  the  underlying  optimizer are
# calculated  as  intersection  of all present constraints. For example, you
# may specify boundary constraint on P[0,0] and equality one:
#     0.1<=P[0,0]<=0.9
#     P[0,0]=0.5
# Such  combination  of  constraints  will  be  silently  reduced  to  their
# intersection, which is P[0,0]=0.5.
# 
# This  function  can  be  used  to  place bound   constraints  on arbitrary
# subset  of  elements  of  P.  Set of constraints is specified by BndL/BndU
# matrices, which may contain arbitrary combination  of  finite  numbers  or
# infinities (like -INF<x<=0.5 or 0.1<=x<+INF).
# 
# You can also use MCPDAddBC() function which allows to ADD bound constraint
# for one element of P without changing constraints for other elements.
# 
# These functions (MCPDSetBC and MCPDAddBC) interact as follows:
# * there is internal matrix of bound constraints which is stored in the
#   MCPD solver
# * MCPDSetBC() replaces this matrix by another one (SET)
# * MCPDAddBC() modifies one element of this matrix and  leaves  other  ones
#   unchanged (ADD)
# * thus  MCPDAddBC()  call  preserves  all  modifications  done by previous
#   calls,  while  MCPDSetBC()  completely discards all changes  done to the
#   equality constraints.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     BndL    -   lower bounds constraints, array[N,N]. Elements of BndL can
#                 be finite numbers or -INF.
#     BndU    -   upper bounds constraints, array[N,N]. Elements of BndU can
#                 be finite numbers or +INF.
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdsetbc(s, bndl, bndu)

mcpdsetec function

#
# This function is used to add equality constraints on the elements  of  the
# transition matrix P.
# 
# MCPD solver has four types of constraints which can be placed on P:
# * user-specified equality constraints (optional)
# * user-specified bound constraints (optional)
# * user-specified general linear constraints (optional)
# * basic constraints (always present):
#   * non-negativity: P[i,j]>=0
#   * consistency: every column of P sums to 1.0
# 
# Final  constraints  which  are  passed  to  the  underlying  optimizer are
# calculated  as  intersection  of all present constraints. For example, you
# may specify boundary constraint on P[0,0] and equality one:
#     0.1<=P[0,0]<=0.9
#     P[0,0]=0.5
# Such  combination  of  constraints  will  be  silently  reduced  to  their
# intersection, which is P[0,0]=0.5.
# 
# This  function  can  be  used  to  place equality constraints on arbitrary
# subset of elements of P. Set of constraints is specified by EC, which  may
# contain either NAN's or finite numbers from [0,1]. NAN denotes absence  of
# constraint, finite number denotes equality constraint on specific  element
# of P.
# 
# You can also  use  MCPDAddEC()  function  which  allows  to  ADD  equality
# constraint  for  one  element  of P without changing constraints for other
# elements.
# 
# These functions (MCPDSetEC and MCPDAddEC) interact as follows:
# * there is internal matrix of equality constraints which is stored in  the
#   MCPD solver
# * MCPDSetEC() replaces this matrix by another one (SET)
# * MCPDAddEC() modifies one element of this matrix and  leaves  other  ones
#   unchanged (ADD)
# * thus  MCPDAddEC()  call  preserves  all  modifications  done by previous
#   calls,  while  MCPDSetEC()  completely discards all changes  done to the
#   equality constraints.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     EC      -   equality constraints, array[N,N]. Elements of  EC  can  be
#                 either NAN's or finite  numbers from  [0,1].  NAN  denotes
#                 absence  of  constraints,  while  finite  value    denotes
#                 equality constraint on the corresponding element of P.
# 
# NOTES:
# 
# 1. infinite values of EC will lead to exception being thrown. Values  less
# than 0.0 or greater than 1.0 will lead to error code being returned  after
# call to MCPDSolve().
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdsetec(s, ec)

mcpdsetlc function

#
# This function is used to set linear equality/inequality constraints on the
# elements of the transition matrix P.
# 
# This function can be used to set one or several general linear constraints
# on the elements of P. Two types of constraints are supported:
# * equality constraints
# * inequality constraints (both less-or-equal and greater-or-equal)
# 
# Coefficients  of  constraints  are  specified  by  matrix  C (one  of  the
# parameters).  One  row  of  C  corresponds  to  one  constraint.   Because
# transition  matrix P has N*N elements,  we  need  N*N columns to store all
# coefficients  (they  are  stored row by row), and one more column to store
# right part - hence C has N*N+1 columns.  Constraint  kind is stored in the
# CT array.
# 
# Thus, I-th linear constraint is
#     P[0,0]*C[I,0] + P[0,1]*C[I,1] + .. + P[0,N-1]*C[I,N-1] +
#         + P[1,0]*C[I,N] + P[1,1]*C[I,N+1] + ... +
#         + P[N-1,N-1]*C[I,N*N-1]  ?=?  C[I,N*N]
# where ?=? can be either "=" (CT[i]=0), "<=" (CT[i]<0) or ">=" (CT[i]>0).
# 
# Your constraint may involve only some subset of P (less than N*N elements).
# For example it can be something like
#     P[0,0] + P[0,1] = 0.5
# In this case you still should pass matrix  with N*N+1 columns, but all its
# elements (except for C[0,0], C[0,1] and C[0,N*N-1]) will be zero.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     C       -   array[K,N*N+1] - coefficients of constraints
#                 (see above for complete description)
#     CT      -   array[K] - constraint types
#                 (see above for complete description)
#     K       -   number of equality/inequality constraints, K>=0:
#                 * if given, only leading K elements of C/CT are used
#                 * if not given, automatically determined from sizes of C/CT
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdsetlc(s, c, ct, k)
SYNTAX: xalglib.mcpdsetlc(s, c, ct)

mcpdsetpredictionweights function

#
# This function is used to change prediction weights
# 
# MCPD solver scales prediction errors as follows
#     Error(P) = ||W*(y-P*x)||^2
# where
#     x is a system state at time t
#     y is a system state at time t+1
#     P is a transition matrix
#     W is a diagonal scaling matrix
# 
# By default, weights are chosen in order  to  minimize  relative prediction
# error instead of absolute one. For example, if one component of  state  is
# about 0.5 in magnitude and another one is about 0.05, then algorithm  will
# make corresponding weights equal to 2.0 and 20.0.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     PW      -   array[N], weights:
#                 * must be non-negative values (exception will be thrown otherwise)
#                 * zero values will be replaced by automatically chosen values
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdsetpredictionweights(s, pw)

mcpdsetprior function

#
# This  function  allows to set prior values used for regularization of your
# problem.
# 
# By default, regularizing term is equal to r*||P-prior_P||^2, where r is  a
# small non-zero value,  P is transition matrix, prior_P is identity matrix,
# ||X||^2 is a sum of squared elements of X.
# 
# This  function  allows  you to change prior values prior_P. You  can  also
# change r with MCPDSetTikhonovRegularizer() function.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     PP      -   array[N,N], matrix of prior values:
#                 1. elements must be real numbers from [0,1]
#                 2. columns must sum to 1.0.
#                 First property is checked (exception is thrown otherwise),
#                 while second one is not checked/enforced.
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdsetprior(s, pp)

mcpdsettikhonovregularizer function

#
# This function allows to  tune  amount  of  Tikhonov  regularization  being
# applied to your problem.
# 
# By default, regularizing term is equal to r*||P-prior_P||^2, where r is  a
# small non-zero value,  P is transition matrix, prior_P is identity matrix,
# ||X||^2 is a sum of squared elements of X.
# 
# This  function  allows  you to change coefficient r. You can  also  change
# prior values with MCPDSetPrior() function.
# 
# INPUT PARAMETERS:
#     S       -   solver
#     V       -   regularization  coefficient, finite non-negative value. It
#                 is  not  recommended  to specify zero value unless you are
#                 pretty sure that you want it.
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdsettikhonovregularizer(s, v)

mcpdsolve function

#
# This function is used to start solution of the MCPD problem.
# 
# After return from this function, you can use MCPDResults() to get solution
# and completion code.
# 
#   -- ALGLIB --
#      Copyright 23.05.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mcpdsolve(s)

Examples:   [1]  [2]  

mcpd_simple1 example

import xalglib



#
# The very simple MCPD example
#
# We have a loan portfolio. Our loans can be in one of two states:
# * normal loans ("good" ones)
# * past due loans ("bad" ones)
#
# We assume that:
# * loans can transition from any state to any other state. In 
#   particular, past due loan can become "good" one at any moment 
#   with same (fixed) probability. Not realistic, but it is toy example :)
# * portfolio size does not change over time
#
# Thus, we have following model
#     state_new = P*state_old
# where
#         ( p00  p01 )
#     P = (          )
#         ( p10  p11 )
#
# We want to model transitions between these two states using MCPD
# approach (Markov Chains for Proportional/Population Data), i.e.
# to restore hidden transition matrix P using actual portfolio data.
# We have:
# * poportional data, i.e. proportion of loans in the normal and past 
#   due states (not portfolio size measured in some currency, although 
#   it is possible to work with population data too)
# * two tracks, i.e. two sequences which describe portfolio
#   evolution from two different starting states: [1,0] (all loans 
#   are "good") and [0.8,0.2] (only 80% of portfolio is in the "good"
#   state)
#
track0 = [[1.00000,0.00000],[0.95000,0.05000],[0.92750,0.07250],[0.91738,0.08263],[0.91282,0.08718]]
track1 = [[0.80000,0.20000],[0.86000,0.14000],[0.88700,0.11300],[0.89915,0.10085]]

s = xalglib.mcpdcreate(2)
xalglib.mcpdaddtrack(s, track0)
xalglib.mcpdaddtrack(s, track1)
xalglib.mcpdsolve(s)
p, rep = xalglib.mcpdresults(s)

#
# Hidden matrix P is equal to
#         ( 0.95  0.50 )
#         (            )
#         ( 0.05  0.50 )
# which means that "good" loans can become "bad" with 5% probability, 
# while "bad" loans will return to good state with 50% probability.
#
print(p) # expected [[0.95,0.50],[0.05,0.50]]

mcpd_simple2 example

import xalglib



#
# Simple MCPD example
#
# We have a loan portfolio. Our loans can be in one of three states:
# * normal loans
# * past due loans
# * charged off loans
#
# We assume that:
# * normal loan can stay normal or become past due (but not charged off)
# * past due loan can stay past due, become normal or charged off
# * charged off loan will stay charged off for the rest of eternity
# * portfolio size does not change over time
# Not realistic, but it is toy example :)
#
# Thus, we have following model
#     state_new = P*state_old
# where
#         ( p00  p01    )
#     P = ( p10  p11    )
#         (      p21  1 )
# i.e. four elements of P are known a priori.
#
# Although it is possible (given enough data) to In order to enforce 
# this property we set equality constraints on these elements.
#
# We want to model transitions between these two states using MCPD
# approach (Markov Chains for Proportional/Population Data), i.e.
# to restore hidden transition matrix P using actual portfolio data.
# We have:
# * poportional data, i.e. proportion of loans in the current and past 
#   due states (not portfolio size measured in some currency, although 
#   it is possible to work with population data too)
# * two tracks, i.e. two sequences which describe portfolio
#   evolution from two different starting states: [1,0,0] (all loans 
#   are "good") and [0.8,0.2,0.0] (only 80% of portfolio is in the "good"
#   state)
#
track0 = [[1.000000,0.000000,0.000000],[0.950000,0.050000,0.000000],[0.927500,0.060000,0.012500],[0.911125,0.061375,0.027500],[0.896256,0.060900,0.042844]]
track1 = [[0.800000,0.200000,0.000000],[0.860000,0.090000,0.050000],[0.862000,0.065500,0.072500],[0.851650,0.059475,0.088875],[0.838805,0.057451,0.103744]]

s = xalglib.mcpdcreate(3)
xalglib.mcpdaddtrack(s, track0)
xalglib.mcpdaddtrack(s, track1)
xalglib.mcpdaddec(s, 0, 2, 0.0)
xalglib.mcpdaddec(s, 1, 2, 0.0)
xalglib.mcpdaddec(s, 2, 2, 1.0)
xalglib.mcpdaddec(s, 2, 0, 0.0)
xalglib.mcpdsolve(s)
p, rep = xalglib.mcpdresults(s)

#
# Hidden matrix P is equal to
#         ( 0.95 0.50      )
#         ( 0.05 0.25      )
#         (      0.25 1.00 ) 
# which means that "good" loans can become past due with 5% probability, 
# while past due loans will become charged off with 25% probability or
# return back to normal state with 50% probability.
#
print(p) # expected [[0.95,0.50,0.00],[0.05,0.25,0.00],[0.00,0.25,1.00]]

minbc module

minbcreport class

#
# This structure stores optimization report:
# * IterationsCount           number of iterations
# * NFEV                      number of gradient evaluations
# * TerminationType           termination type (see below)
# 
# TERMINATION CODES
# 
# TerminationType field contains completion code, which can be:
#   -8    internal integrity control detected  infinite  or  NAN  values  in
#         function/gradient. Abnormal termination signalled.
#   -7    gradient verification failed.
#         See MinBCSetGradientCheck() for more information.
#   -3    inconsistent constraints.
#    1    relative function improvement is no more than EpsF.
#    2    relative step is no more than EpsX.
#    4    gradient norm is no more than EpsG
#    5    MaxIts steps was taken
#    7    stopping conditions are too stringent,
#         further improvement is impossible,
#         X contains best point found so far.
#    8    terminated by user who called minbcrequesttermination(). X contains
#         point which was "current accepted" when  termination  request  was
#         submitted.
# 
# ADDITIONAL FIELDS
# 
# There are additional fields which can be used for debugging:
# * DebugEqErr                error in the equality constraints (2-norm)
# * DebugFS                   f, calculated at projection of initial point
#                             to the feasible set
# * DebugFF                   f, calculated at the final point
# * DebugDX                   |X_start-X_final|
#

class minbcreport(object):
    ...

minbcstate class

#
# This object stores nonlinear optimizer state.
# You should use functions provided by MinBC subpackage to work with this
# object
#

class minbcstate(object):
    ...

minbccreate function

#
#                      BOX CONSTRAINED OPTIMIZATION
#           WITH FAST ACTIVATION OF MULTIPLE BOX CONSTRAINTS
# 
# DESCRIPTION:
# The  subroutine  minimizes  function   F(x) of N arguments subject  to box
# constraints (with some of box constraints actually being equality ones).
# 
# This optimizer uses algorithm similar to that of MinBLEIC (optimizer  with
# general linear constraints), but presence of box-only  constraints  allows
# us to use faster constraint activation strategies. On large-scale problems,
# with multiple constraints active at the solution, this  optimizer  can  be
# several times faster than BLEIC.
# 
# REQUIREMENTS:
# * user must provide function value and gradient
# * starting point X0 must be feasible or
#   not too far away from the feasible set
# * grad(f) must be Lipschitz continuous on a level set:
#   L = { x : f(x)<=f(x0) }
# * function must be defined everywhere on the feasible set F
# 
# USAGE:
# 
# Constrained optimization if far more complex than the unconstrained one.
# Here we give very brief outline of the BC optimizer. We strongly recommend
# you to read examples in the ALGLIB Reference Manual and to read ALGLIB User Guide
# on optimization, which is available at http://www.alglib.net/optimization/
# 
# 1. User initializes algorithm state with MinBCCreate() call
# 
# 2. USer adds box constraints by calling MinBCSetBC() function.
# 
# 3. User sets stopping conditions with MinBCSetCond().
# 
# 4. User calls MinBCOptimize() function which takes algorithm  state and
#    pointer (delegate, etc.) to callback function which calculates F/G.
# 
# 5. User calls MinBCResults() to get solution
# 
# 6. Optionally user may call MinBCRestartFrom() to solve another problem
#    with same N but another starting point.
#    MinBCRestartFrom() allows to reuse already initialized structure.
# 
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size ofX
#     X       -   starting point, array[N]:
#                 * it is better to set X to a feasible point
#                 * but X can be infeasible, in which case algorithm will try
#                   to find feasible point first, using X as initial
#                   approximation.
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minbccreate(n, x)
SYNTAX: state = xalglib.minbccreate(x)

Examples:   [1]  

minbccreatef function

#
# The subroutine is finite difference variant of MinBCCreate().  It  uses
# finite differences in order to differentiate target function.
# 
# Description below contains information which is specific to  this function
# only. We recommend to read comments on MinBCCreate() in  order  to  get
# more information about creation of BC optimizer.
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     X       -   starting point, array[0..N-1].
#     DiffStep-   differentiation step, >0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTES:
# 1. algorithm uses 4-point central formula for differentiation.
# 2. differentiation step along I-th axis is equal to DiffStep*S[I] where
#    S[] is scaling vector which can be set by MinBCSetScale() call.
# 3. we recommend you to use moderate values of  differentiation  step.  Too
#    large step will result in too large truncation  errors, while too small
#    step will result in too large numerical  errors.  1.0E-6  can  be  good
#    value to start with.
# 4. Numerical  differentiation  is   very   inefficient  -   one   gradient
#    calculation needs 4*N function evaluations. This function will work for
#    any N - either small (1...10), moderate (10...100) or  large  (100...).
#    However, performance penalty will be too severe for any N's except  for
#    small ones.
#    We should also say that code which relies on numerical  differentiation
#    is  less  robust and precise. CG needs exact gradient values. Imprecise
#    gradient may slow  down  convergence, especially  on  highly  nonlinear
#    problems.
#    Thus  we  recommend to use this function for fast prototyping on small-
#    dimensional problems only, and to implement analytical gradient as soon
#    as possible.
# 
#   -- ALGLIB --
#      Copyright 16.05.2011 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minbccreatef(n, x, diffstep)
SYNTAX: state = xalglib.minbccreatef(x, diffstep)

Examples:   [1]  

minbcoptimize function

#
# This family of functions is used to launcn iterations of nonlinear optimizer
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     func    -   callback which calculates function (or merit function)
#                 value func at given point x
#     grad    -   callback which calculates function (or merit function)
#                 value func and gradient grad at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# NOTES:
# 
# 1. This function has two different implementations: one which  uses  exact
#    (analytical) user-supplied gradient,  and one which uses function value
#    only  and  numerically  differentiates  function  in  order  to  obtain
#    gradient.
# 
#    Depending  on  the  specific  function  used to create optimizer object
#    (either  MinBCCreate() for analytical gradient or  MinBCCreateF()
#    for numerical differentiation) you should choose appropriate variant of
#    MinBCOptimize() - one  which  accepts  function  AND gradient or one
#    which accepts function ONLY.
# 
#    Be careful to choose variant of MinBCOptimize() which corresponds to
#    your optimization scheme! Table below lists different  combinations  of
#    callback (function/gradient) passed to MinBCOptimize()  and specific
#    function used to create optimizer.
# 
# 
#                      |         USER PASSED TO MinBCOptimize()
#    CREATED WITH      |  function only   |  function and gradient
#    ------------------------------------------------------------
#    MinBCCreateF()    |     works               FAILS
#    MinBCCreate()     |     FAILS               works
# 
#    Here "FAIL" denotes inappropriate combinations  of  optimizer  creation
#    function  and  MinBCOptimize()  version.   Attemps   to   use   such
#    combination (for  example,  to  create optimizer with MinBCCreateF()
#    and  to  pass  gradient  information  to  MinCGOptimize()) will lead to
#    exception being thrown. Either  you  did  not pass gradient when it WAS
#    needed or you passed gradient when it was NOT needed.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcoptimize_f(state, func, rep = None, param = None)
SYNTAX: xalglib.minbcoptimize_g(state, grad, rep = None, param = None)

Examples:   [1]  [2]  

minbcrequesttermination function

#
# This subroutine submits request for termination of running  optimizer.  It
# should be called from user-supplied callback when user decides that it  is
# time to "smoothly" terminate optimization process.  As  result,  optimizer
# stops at point which was "current accepted" when termination  request  was
# submitted and returns error code 8 (successful termination).
# 
# INPUT PARAMETERS:
#     State   -   optimizer structure
# 
# NOTE: after  request  for  termination  optimizer  may   perform   several
#       additional calls to user-supplied callbacks. It does  NOT  guarantee
#       to stop immediately - it just guarantees that these additional calls
#       will be discarded later.
# 
# NOTE: calling this function on optimizer which is NOT running will have no
#       effect.
# 
# NOTE: multiple calls to this function are possible. First call is counted,
#       subsequent calls are silently ignored.
# 
#   -- ALGLIB --
#      Copyright 08.10.2014 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcrequesttermination(state)

minbcrestartfrom function

#
# This subroutine restarts algorithm from new point.
# All optimization parameters (including constraints) are left unchanged.
# 
# This  function  allows  to  solve multiple  optimization  problems  (which
# must have  same number of dimensions) without object reallocation penalty.
# 
# INPUT PARAMETERS:
#     State   -   structure previously allocated with MinBCCreate call.
#     X       -   new starting point.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcrestartfrom(state, x)

minbcresults function

#
# BC results
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[0..N-1], solution
#     Rep     -   optimization report. You should check Rep.TerminationType
#                 in  order  to  distinguish  successful  termination  from
#                 unsuccessful one:
#                 * -8    internal integrity control  detected  infinite or
#                         NAN   values   in   function/gradient.   Abnormal
#                         termination signalled.
#                 * -7   gradient verification failed.
#                        See MinBCSetGradientCheck() for more information.
#                 * -3   inconsistent constraints.
#                 *  1   relative function improvement is no more than EpsF.
#                 *  2   scaled step is no more than EpsX.
#                 *  4   scaled gradient norm is no more than EpsG.
#                 *  5   MaxIts steps was taken
#                 *  8   terminated by user who called minbcrequesttermination().
#                        X contains point which was "current accepted"  when
#                        termination request was submitted.
#                 More information about fields of this  structure  can  be
#                 found in the comments on MinBCReport datatype.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minbcresults(state)

Examples:   [1]  [2]  

minbcresultsbuf function

#
# BC results
# 
# Buffered implementation of MinBCResults() which uses pre-allocated buffer
# to store X[]. If buffer size is  too  small,  it  resizes  buffer.  It  is
# intended to be used in the inner cycles of performance critical algorithms
# where array reallocation penalty is too large to be ignored.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minbcresultsbuf(state, x, rep)

minbcsetbc function

#
# This function sets boundary constraints for BC optimizer.
# 
# Boundary constraints are inactive by default (after initial creation).
# They are preserved after algorithm restart with MinBCRestartFrom().
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     BndL    -   lower bounds, array[N].
#                 If some (all) variables are unbounded, you may specify
#                 very small number or -INF.
#     BndU    -   upper bounds, array[N].
#                 If some (all) variables are unbounded, you may specify
#                 very large number or +INF.
# 
# NOTE 1: it is possible to specify BndL[i]=BndU[i]. In this case I-th
# variable will be "frozen" at X[i]=BndL[i]=BndU[i].
# 
# NOTE 2: this solver has following useful properties:
# * bound constraints are always satisfied exactly
# * function is evaluated only INSIDE area specified by  bound  constraints,
#   even  when  numerical  differentiation is used (algorithm adjusts  nodes
#   according to boundary constraints)
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetbc(state, bndl, bndu)

Examples:   [1]  [2]  

minbcsetcond function

#
# This function sets stopping conditions for the optimizer.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     EpsG    -   >=0
#                 The  subroutine  finishes  its  work   if   the  condition
#                 |v|<EpsG is satisfied, where:
#                 * |.| means Euclidian norm
#                 * v - scaled gradient vector, v[i]=g[i]*s[i]
#                 * g - gradient
#                 * s - scaling coefficients set by MinBCSetScale()
#     EpsF    -   >=0
#                 The  subroutine  finishes  its work if on k+1-th iteration
#                 the  condition  |F(k+1)-F(k)|<=EpsF*max{|F(k)|,|F(k+1)|,1}
#                 is satisfied.
#     EpsX    -   >=0
#                 The subroutine finishes its work if  on  k+1-th  iteration
#                 the condition |v|<=EpsX is fulfilled, where:
#                 * |.| means Euclidian norm
#                 * v - scaled step vector, v[i]=dx[i]/s[i]
#                 * dx - step vector, dx=X(k+1)-X(k)
#                 * s - scaling coefficients set by MinBCSetScale()
#     MaxIts  -   maximum number of iterations. If MaxIts=0, the  number  of
#                 iterations is unlimited.
# 
# Passing EpsG=0, EpsF=0 and EpsX=0 and MaxIts=0 (simultaneously) will lead
# to automatic stopping criterion selection.
# 
# NOTE: when SetCond() called with non-zero MaxIts, BC solver may perform
#       slightly more than MaxIts iterations. I.e., MaxIts  sets  non-strict
#       limit on iterations count.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetcond(state, epsg, epsf, epsx, maxits)

Examples:   [1]  [2]  

minbcsetgradientcheck function

#
# This  subroutine  turns  on  verification  of  the  user-supplied analytic
# gradient:
# * user calls this subroutine before optimization begins
# * MinBCOptimize() is called
# * prior to  actual  optimization, for each component  of  parameters being
#   optimized X[i] algorithm performs following steps:
#   * two trial steps are made to X[i]-TestStep*S[i] and X[i]+TestStep*S[i],
#     where X[i] is i-th component of the initial point and S[i] is a  scale
#     of i-th parameter
#   * if needed, steps are bounded with respect to constraints on X[]
#   * F(X) is evaluated at these trial points
#   * we perform one more evaluation in the middle point of the interval
#   * we  build  cubic  model using function values and derivatives at trial
#     points and we compare its prediction with actual value in  the  middle
#     point
#   * in case difference between prediction and actual value is higher  than
#     some predetermined threshold, algorithm stops with completion code -7;
#     Rep.VarIdx is set to index of the parameter with incorrect derivative.
# * after verification is over, algorithm proceeds to the actual optimization.
# 
# NOTE 1: verification  needs  N (parameters count) gradient evaluations. It
#         is very costly and you should use  it  only  for  low  dimensional
#         problems,  when  you  want  to  be  sure  that  you've   correctly
#         calculated  analytic  derivatives.  You  should  not use it in the
#         production code (unless you want to check derivatives provided  by
#         some third party).
# 
# NOTE 2: you  should  carefully  choose  TestStep. Value which is too large
#         (so large that function behaviour is significantly non-cubic) will
#         lead to false alarms. You may use  different  step  for  different
#         parameters by means of setting scale with MinBCSetScale().
# 
# NOTE 3: this function may lead to false positives. In case it reports that
#         I-th  derivative was calculated incorrectly, you may decrease test
#         step  and  try  one  more  time  - maybe your function changes too
#         sharply  and  your  step  is  too  large for such rapidly chanding
#         function.
# 
# INPUT PARAMETERS:
#     State       -   structure used to store algorithm state
#     TestStep    -   verification step:
#                     * TestStep=0 turns verification off
#                     * TestStep>0 activates verification
# 
#   -- ALGLIB --
#      Copyright 15.06.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetgradientcheck(state, teststep)

minbcsetprecdefault function

#
# Modification of the preconditioner: preconditioning is turned off.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetprecdefault(state)

minbcsetprecdiag function

#
# Modification  of  the  preconditioner:  diagonal of approximate Hessian is
# used.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     D       -   diagonal of the approximate Hessian, array[0..N-1],
#                 (if larger, only leading N elements are used).
# 
# NOTE 1: D[i] should be positive. Exception will be thrown otherwise.
# 
# NOTE 2: you should pass diagonal of approximate Hessian - NOT ITS INVERSE.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetprecdiag(state, d)

minbcsetprecscale function

#
# Modification of the preconditioner: scale-based diagonal preconditioning.
# 
# This preconditioning mode can be useful when you  don't  have  approximate
# diagonal of Hessian, but you know that your  variables  are  badly  scaled
# (for  example,  one  variable is in [1,10], and another in [1000,100000]),
# and most part of the ill-conditioning comes from different scales of vars.
# 
# In this case simple  scale-based  preconditioner,  with H[i] = 1/(s[i]^2),
# can greatly improve convergence.
# 
# IMPRTANT: you should set scale of your variables  with  MinBCSetScale()
# call  (before  or after MinBCSetPrecScale() call). Without knowledge of
# the scale of your variables scale-based preconditioner will be  just  unit
# matrix.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetprecscale(state)

minbcsetscale function

#
# This function sets scaling coefficients for BC optimizer.
# 
# ALGLIB optimizers use scaling matrices to test stopping  conditions  (step
# size and gradient are scaled before comparison with tolerances).  Scale of
# the I-th variable is a translation invariant measure of:
# a) "how large" the variable is
# b) how large the step should be to make significant changes in the function
# 
# Scaling is also used by finite difference variant of the optimizer  - step
# along I-th axis is equal to DiffStep*S[I].
# 
# In  most  optimizers  (and  in  the  BC  too)  scaling is NOT a form of
# preconditioning. It just  affects  stopping  conditions.  You  should  set
# preconditioner  by  separate  call  to  one  of  the  MinBCSetPrec...()
# functions.
# 
# There is a special  preconditioning  mode, however,  which  uses   scaling
# coefficients to form diagonal preconditioning matrix. You  can  turn  this
# mode on, if you want.   But  you should understand that scaling is not the
# same thing as preconditioning - these are two different, although  related
# forms of tuning solver.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     S       -   array[N], non-zero scaling coefficients
#                 S[i] may be negative, sign doesn't matter.
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetscale(state, s)

minbcsetstpmax function

#
# This function sets maximum step length
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     StpMax  -   maximum step length, >=0. Set StpMax to 0.0,  if you don't
#                 want to limit step length.
# 
# Use this subroutine when you optimize target function which contains exp()
# or  other  fast  growing  functions,  and optimization algorithm makes too
# large  steps  which  lead   to overflow. This function allows us to reject
# steps  that  are  too  large  (and  therefore  expose  us  to the possible
# overflow) without actually calculating function value at the x+stp*d.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetstpmax(state, stpmax)

minbcsetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# If NeedXRep is True, algorithm will call rep() callback function if  it is
# provided to MinBCOptimize().
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbcsetxrep(state, needxrep)

minbc_d_1 example

import xalglib

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# subject to bound constraints -1<=x<=+1, -1<=y<=+1, using MinBC optimizer.
#
x = [0,0]
bndl = [-1,-1]
bndu = [+1,+1]

#
# These variables define stopping conditions for the optimizer.
#
# We use very simple condition - |g|<=epsg
#
epsg = 0.000001
epsf = 0
epsx = 0
maxits = 0

#
# Now we are ready to actually optimize something:
# * first we create optimizer
# * we add boundary constraints
# * we tune stopping conditions
# * and, finally, optimize and obtain results...
#
state = xalglib.minbccreate(x)
xalglib.minbcsetbc(state, bndl, bndu)
xalglib.minbcsetcond(state, epsg, epsf, epsx, maxits)
xalglib.minbcoptimize_g(state, function1_grad)
x, rep = xalglib.minbcresults(state)

#
# ...and evaluate these results
#
print(rep.terminationtype) # expected 4
print(x) # expected [-1,1]

minbc_numdiff example

import xalglib

def function1_func(x, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    #
    return 100*(x[0]+3)**4 + (x[1]-3)**4

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# subject to bound constraints -1<=x<=+1, -1<=y<=+1, using MinBC optimizer.
#
x = [0,0]
bndl = [-1,-1]
bndu = [+1,+1]

#
# These variables define stopping conditions for the optimizer.
#
# We use very simple condition - |g|<=epsg
#
epsg = 0.000001
epsf = 0
epsx = 0
maxits = 0

#
# This variable contains differentiation step
#
diffstep = 1.0e-6

#
# Now we are ready to actually optimize something:
# * first we create optimizer
# * we add boundary constraints
# * we tune stopping conditions
# * and, finally, optimize and obtain results...
#
state = xalglib.minbccreatef(x, diffstep)
xalglib.minbcsetbc(state, bndl, bndu)
xalglib.minbcsetcond(state, epsg, epsf, epsx, maxits)
xalglib.minbcoptimize_f(state, function1_func)
x, rep = xalglib.minbcresults(state)

#
# ...and evaluate these results
#
print(rep.terminationtype) # expected 4
print(x) # expected [-1,1]

minbleic module

minbleicreport class

#
# This structure stores optimization report:
# * IterationsCount           number of iterations
# * NFEV                      number of gradient evaluations
# * TerminationType           termination type (see below)
# 
# TERMINATION CODES
# 
# TerminationType field contains completion code, which can be:
#   -8    internal integrity control detected  infinite  or  NAN  values  in
#         function/gradient. Abnormal termination signalled.
#   -7    gradient verification failed.
#         See MinBLEICSetGradientCheck() for more information.
#   -3    inconsistent constraints. Feasible point is
#         either nonexistent or too hard to find. Try to
#         restart optimizer with better initial approximation
#    1    relative function improvement is no more than EpsF.
#    2    relative step is no more than EpsX.
#    4    gradient norm is no more than EpsG
#    5    MaxIts steps was taken
#    7    stopping conditions are too stringent,
#         further improvement is impossible,
#         X contains best point found so far.
#    8    terminated by user who called minbleicrequesttermination(). X contains
#         point which was "current accepted" when  termination  request  was
#         submitted.
# 
# ADDITIONAL FIELDS
# 
# There are additional fields which can be used for debugging:
# * DebugEqErr                error in the equality constraints (2-norm)
# * DebugFS                   f, calculated at projection of initial point
#                             to the feasible set
# * DebugFF                   f, calculated at the final point
# * DebugDX                   |X_start-X_final|
#

class minbleicreport(object):
    ...

minbleicstate class

#
# This object stores nonlinear optimizer state.
# You should use functions provided by MinBLEIC subpackage to work with this
# object
#

class minbleicstate(object):
    ...

minbleiccreate function

#
#                      BOUND CONSTRAINED OPTIMIZATION
#        WITH ADDITIONAL LINEAR EQUALITY AND INEQUALITY CONSTRAINTS
# 
# DESCRIPTION:
# The  subroutine  minimizes  function   F(x)  of N arguments subject to any
# combination of:
# * bound constraints
# * linear inequality constraints
# * linear equality constraints
# 
# REQUIREMENTS:
# * user must provide function value and gradient
# * starting point X0 must be feasible or
#   not too far away from the feasible set
# * grad(f) must be Lipschitz continuous on a level set:
#   L = { x : f(x)<=f(x0) }
# * function must be defined everywhere on the feasible set F
# 
# USAGE:
# 
# Constrained optimization if far more complex than the unconstrained one.
# Here we give very brief outline of the BLEIC optimizer. We strongly recommend
# you to read examples in the ALGLIB Reference Manual and to read ALGLIB User Guide
# on optimization, which is available at http://www.alglib.net/optimization/
# 
# 1. User initializes algorithm state with MinBLEICCreate() call
# 
# 2. USer adds boundary and/or linear constraints by calling
#    MinBLEICSetBC() and MinBLEICSetLC() functions.
# 
# 3. User sets stopping conditions with MinBLEICSetCond().
# 
# 4. User calls MinBLEICOptimize() function which takes algorithm  state and
#    pointer (delegate, etc.) to callback function which calculates F/G.
# 
# 5. User calls MinBLEICResults() to get solution
# 
# 6. Optionally user may call MinBLEICRestartFrom() to solve another problem
#    with same N but another starting point.
#    MinBLEICRestartFrom() allows to reuse already initialized structure.
# 
# NOTE: if you have box-only constraints (no  general  linear  constraints),
#       then MinBC optimizer can be better option. It uses  special,  faster
#       constraint activation method, which performs better on problems with
#       multiple constraints active at the solution.
# 
#       On small-scale problems performance of MinBC is similar to  that  of
#       MinBLEIC, but on large-scale ones (hundreds and thousands of  active
#       constraints) it can be several times faster than MinBLEIC.
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size ofX
#     X       -   starting point, array[N]:
#                 * it is better to set X to a feasible point
#                 * but X can be infeasible, in which case algorithm will try
#                   to find feasible point first, using X as initial
#                   approximation.
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minbleiccreate(n, x)
SYNTAX: state = xalglib.minbleiccreate(x)

Examples:   [1]  [2]  [3]  

minbleiccreatef function

#
# The subroutine is finite difference variant of MinBLEICCreate().  It  uses
# finite differences in order to differentiate target function.
# 
# Description below contains information which is specific to  this function
# only. We recommend to read comments on MinBLEICCreate() in  order  to  get
# more information about creation of BLEIC optimizer.
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     X       -   starting point, array[0..N-1].
#     DiffStep-   differentiation step, >0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTES:
# 1. algorithm uses 4-point central formula for differentiation.
# 2. differentiation step along I-th axis is equal to DiffStep*S[I] where
#    S[] is scaling vector which can be set by MinBLEICSetScale() call.
# 3. we recommend you to use moderate values of  differentiation  step.  Too
#    large step will result in too large truncation  errors, while too small
#    step will result in too large numerical  errors.  1.0E-6  can  be  good
#    value to start with.
# 4. Numerical  differentiation  is   very   inefficient  -   one   gradient
#    calculation needs 4*N function evaluations. This function will work for
#    any N - either small (1...10), moderate (10...100) or  large  (100...).
#    However, performance penalty will be too severe for any N's except  for
#    small ones.
#    We should also say that code which relies on numerical  differentiation
#    is  less  robust and precise. CG needs exact gradient values. Imprecise
#    gradient may slow  down  convergence, especially  on  highly  nonlinear
#    problems.
#    Thus  we  recommend to use this function for fast prototyping on small-
#    dimensional problems only, and to implement analytical gradient as soon
#    as possible.
# 
#   -- ALGLIB --
#      Copyright 16.05.2011 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minbleiccreatef(n, x, diffstep)
SYNTAX: state = xalglib.minbleiccreatef(x, diffstep)

Examples:   [1]  

minbleicoptimize function

#
# This family of functions is used to launcn iterations of nonlinear optimizer
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     func    -   callback which calculates function (or merit function)
#                 value func at given point x
#     grad    -   callback which calculates function (or merit function)
#                 value func and gradient grad at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# NOTES:
# 
# 1. This function has two different implementations: one which  uses  exact
#    (analytical) user-supplied gradient,  and one which uses function value
#    only  and  numerically  differentiates  function  in  order  to  obtain
#    gradient.
# 
#    Depending  on  the  specific  function  used to create optimizer object
#    (either  MinBLEICCreate() for analytical gradient or  MinBLEICCreateF()
#    for numerical differentiation) you should choose appropriate variant of
#    MinBLEICOptimize() - one  which  accepts  function  AND gradient or one
#    which accepts function ONLY.
# 
#    Be careful to choose variant of MinBLEICOptimize() which corresponds to
#    your optimization scheme! Table below lists different  combinations  of
#    callback (function/gradient) passed to MinBLEICOptimize()  and specific
#    function used to create optimizer.
# 
# 
#                      |         USER PASSED TO MinBLEICOptimize()
#    CREATED WITH      |  function only   |  function and gradient
#    ------------------------------------------------------------
#    MinBLEICCreateF() |     work                FAIL
#    MinBLEICCreate()  |     FAIL                work
# 
#    Here "FAIL" denotes inappropriate combinations  of  optimizer  creation
#    function  and  MinBLEICOptimize()  version.   Attemps   to   use   such
#    combination (for  example,  to  create optimizer with MinBLEICCreateF()
#    and  to  pass  gradient  information  to  MinCGOptimize()) will lead to
#    exception being thrown. Either  you  did  not pass gradient when it WAS
#    needed or you passed gradient when it was NOT needed.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicoptimize_f(state, func, rep = None, param = None)
SYNTAX: xalglib.minbleicoptimize_g(state, grad, rep = None, param = None)

Examples:   [1]  [2]  [3]  [4]  

minbleicrequesttermination function

#
# This subroutine submits request for termination of running  optimizer.  It
# should be called from user-supplied callback when user decides that it  is
# time to "smoothly" terminate optimization process.  As  result,  optimizer
# stops at point which was "current accepted" when termination  request  was
# submitted and returns error code 8 (successful termination).
# 
# INPUT PARAMETERS:
#     State   -   optimizer structure
# 
# NOTE: after  request  for  termination  optimizer  may   perform   several
#       additional calls to user-supplied callbacks. It does  NOT  guarantee
#       to stop immediately - it just guarantees that these additional calls
#       will be discarded later.
# 
# NOTE: calling this function on optimizer which is NOT running will have no
#       effect.
# 
# NOTE: multiple calls to this function are possible. First call is counted,
#       subsequent calls are silently ignored.
# 
#   -- ALGLIB --
#      Copyright 08.10.2014 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicrequesttermination(state)

minbleicrestartfrom function

#
# This subroutine restarts algorithm from new point.
# All optimization parameters (including constraints) are left unchanged.
# 
# This  function  allows  to  solve multiple  optimization  problems  (which
# must have  same number of dimensions) without object reallocation penalty.
# 
# INPUT PARAMETERS:
#     State   -   structure previously allocated with MinBLEICCreate call.
#     X       -   new starting point.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicrestartfrom(state, x)

minbleicresults function

#
# BLEIC results
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[0..N-1], solution
#     Rep     -   optimization report. You should check Rep.TerminationType
#                 in  order  to  distinguish  successful  termination  from
#                 unsuccessful one:
#                 * -8    internal integrity control  detected  infinite or
#                         NAN   values   in   function/gradient.   Abnormal
#                         termination signalled.
#                 * -7   gradient verification failed.
#                        See MinBLEICSetGradientCheck() for more information.
#                 * -3   inconsistent constraints. Feasible point is
#                        either nonexistent or too hard to find. Try to
#                        restart optimizer with better initial approximation
#                 *  1   relative function improvement is no more than EpsF.
#                 *  2   scaled step is no more than EpsX.
#                 *  4   scaled gradient norm is no more than EpsG.
#                 *  5   MaxIts steps was taken
#                 *  8   terminated by user who called minbleicrequesttermination().
#                        X contains point which was "current accepted"  when
#                        termination request was submitted.
#                 More information about fields of this  structure  can  be
#                 found in the comments on MinBLEICReport datatype.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minbleicresults(state)

Examples:   [1]  [2]  [3]  [4]  

minbleicresultsbuf function

#
# BLEIC results
# 
# Buffered implementation of MinBLEICResults() which uses pre-allocated buffer
# to store X[]. If buffer size is  too  small,  it  resizes  buffer.  It  is
# intended to be used in the inner cycles of performance critical algorithms
# where array reallocation penalty is too large to be ignored.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minbleicresultsbuf(state, x, rep)

minbleicsetbc function

#
# This function sets boundary constraints for BLEIC optimizer.
# 
# Boundary constraints are inactive by default (after initial creation).
# They are preserved after algorithm restart with MinBLEICRestartFrom().
# 
# NOTE: if you have box-only constraints (no  general  linear  constraints),
#       then MinBC optimizer can be better option. It uses  special,  faster
#       constraint activation method, which performs better on problems with
#       multiple constraints active at the solution.
# 
#       On small-scale problems performance of MinBC is similar to  that  of
#       MinBLEIC, but on large-scale ones (hundreds and thousands of  active
#       constraints) it can be several times faster than MinBLEIC.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     BndL    -   lower bounds, array[N].
#                 If some (all) variables are unbounded, you may specify
#                 very small number or -INF.
#     BndU    -   upper bounds, array[N].
#                 If some (all) variables are unbounded, you may specify
#                 very large number or +INF.
# 
# NOTE 1: it is possible to specify BndL[i]=BndU[i]. In this case I-th
# variable will be "frozen" at X[i]=BndL[i]=BndU[i].
# 
# NOTE 2: this solver has following useful properties:
# * bound constraints are always satisfied exactly
# * function is evaluated only INSIDE area specified by  bound  constraints,
#   even  when  numerical  differentiation is used (algorithm adjusts  nodes
#   according to boundary constraints)
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetbc(state, bndl, bndu)

Examples:   [1]  [2]  

minbleicsetcond function

#
# This function sets stopping conditions for the optimizer.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     EpsG    -   >=0
#                 The  subroutine  finishes  its  work   if   the  condition
#                 |v|<EpsG is satisfied, where:
#                 * |.| means Euclidian norm
#                 * v - scaled gradient vector, v[i]=g[i]*s[i]
#                 * g - gradient
#                 * s - scaling coefficients set by MinBLEICSetScale()
#     EpsF    -   >=0
#                 The  subroutine  finishes  its work if on k+1-th iteration
#                 the  condition  |F(k+1)-F(k)|<=EpsF*max{|F(k)|,|F(k+1)|,1}
#                 is satisfied.
#     EpsX    -   >=0
#                 The subroutine finishes its work if  on  k+1-th  iteration
#                 the condition |v|<=EpsX is fulfilled, where:
#                 * |.| means Euclidian norm
#                 * v - scaled step vector, v[i]=dx[i]/s[i]
#                 * dx - step vector, dx=X(k+1)-X(k)
#                 * s - scaling coefficients set by MinBLEICSetScale()
#     MaxIts  -   maximum number of iterations. If MaxIts=0, the  number  of
#                 iterations is unlimited.
# 
# Passing EpsG=0, EpsF=0 and EpsX=0 and MaxIts=0 (simultaneously) will lead
# to automatic stopping criterion selection.
# 
# NOTE: when SetCond() called with non-zero MaxIts, BLEIC solver may perform
#       slightly more than MaxIts iterations. I.e., MaxIts  sets  non-strict
#       limit on iterations count.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetcond(state, epsg, epsf, epsx, maxits)

Examples:   [1]  [2]  [3]  

minbleicsetgradientcheck function

#
# This  subroutine  turns  on  verification  of  the  user-supplied analytic
# gradient:
# * user calls this subroutine before optimization begins
# * MinBLEICOptimize() is called
# * prior to  actual  optimization, for each component  of  parameters being
#   optimized X[i] algorithm performs following steps:
#   * two trial steps are made to X[i]-TestStep*S[i] and X[i]+TestStep*S[i],
#     where X[i] is i-th component of the initial point and S[i] is a  scale
#     of i-th parameter
#   * if needed, steps are bounded with respect to constraints on X[]
#   * F(X) is evaluated at these trial points
#   * we perform one more evaluation in the middle point of the interval
#   * we  build  cubic  model using function values and derivatives at trial
#     points and we compare its prediction with actual value in  the  middle
#     point
#   * in case difference between prediction and actual value is higher  than
#     some predetermined threshold, algorithm stops with completion code -7;
#     Rep.VarIdx is set to index of the parameter with incorrect derivative.
# * after verification is over, algorithm proceeds to the actual optimization.
# 
# NOTE 1: verification  needs  N (parameters count) gradient evaluations. It
#         is very costly and you should use  it  only  for  low  dimensional
#         problems,  when  you  want  to  be  sure  that  you've   correctly
#         calculated  analytic  derivatives.  You  should  not use it in the
#         production code (unless you want to check derivatives provided  by
#         some third party).
# 
# NOTE 2: you  should  carefully  choose  TestStep. Value which is too large
#         (so large that function behaviour is significantly non-cubic) will
#         lead to false alarms. You may use  different  step  for  different
#         parameters by means of setting scale with MinBLEICSetScale().
# 
# NOTE 3: this function may lead to false positives. In case it reports that
#         I-th  derivative was calculated incorrectly, you may decrease test
#         step  and  try  one  more  time  - maybe your function changes too
#         sharply  and  your  step  is  too  large for such rapidly chanding
#         function.
# 
# INPUT PARAMETERS:
#     State       -   structure used to store algorithm state
#     TestStep    -   verification step:
#                     * TestStep=0 turns verification off
#                     * TestStep>0 activates verification
# 
#   -- ALGLIB --
#      Copyright 15.06.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetgradientcheck(state, teststep)

minbleicsetlc function

#
# This function sets linear constraints for BLEIC optimizer.
# 
# Linear constraints are inactive by default (after initial creation).
# They are preserved after algorithm restart with MinBLEICRestartFrom().
# 
# INPUT PARAMETERS:
#     State   -   structure previously allocated with MinBLEICCreate call.
#     C       -   linear constraints, array[K,N+1].
#                 Each row of C represents one constraint, either equality
#                 or inequality (see below):
#                 * first N elements correspond to coefficients,
#                 * last element corresponds to the right part.
#                 All elements of C (including right part) must be finite.
#     CT      -   type of constraints, array[K]:
#                 * if CT[i]>0, then I-th constraint is C[i,*]*x >= C[i,n+1]
#                 * if CT[i]=0, then I-th constraint is C[i,*]*x  = C[i,n+1]
#                 * if CT[i]<0, then I-th constraint is C[i,*]*x <= C[i,n+1]
#     K       -   number of equality/inequality constraints, K>=0:
#                 * if given, only leading K elements of C/CT are used
#                 * if not given, automatically determined from sizes of C/CT
# 
# NOTE 1: linear (non-bound) constraints are satisfied only approximately:
# * there always exists some minor violation (about Epsilon in magnitude)
#   due to rounding errors
# * numerical differentiation, if used, may  lead  to  function  evaluations
#   outside  of the feasible  area,   because   algorithm  does  NOT  change
#   numerical differentiation formula according to linear constraints.
# If you want constraints to be  satisfied  exactly, try to reformulate your
# problem  in  such  manner  that  all constraints will become boundary ones
# (this kind of constraints is always satisfied exactly, both in  the  final
# solution and in all intermediate points).
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetlc(state, c, ct, k)
SYNTAX: xalglib.minbleicsetlc(state, c, ct)

Examples:   [1]  

minbleicsetprecdefault function

#
# Modification of the preconditioner: preconditioning is turned off.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetprecdefault(state)

minbleicsetprecdiag function

#
# Modification  of  the  preconditioner:  diagonal of approximate Hessian is
# used.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     D       -   diagonal of the approximate Hessian, array[0..N-1],
#                 (if larger, only leading N elements are used).
# 
# NOTE 1: D[i] should be positive. Exception will be thrown otherwise.
# 
# NOTE 2: you should pass diagonal of approximate Hessian - NOT ITS INVERSE.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetprecdiag(state, d)

minbleicsetprecscale function

#
# Modification of the preconditioner: scale-based diagonal preconditioning.
# 
# This preconditioning mode can be useful when you  don't  have  approximate
# diagonal of Hessian, but you know that your  variables  are  badly  scaled
# (for  example,  one  variable is in [1,10], and another in [1000,100000]),
# and most part of the ill-conditioning comes from different scales of vars.
# 
# In this case simple  scale-based  preconditioner,  with H[i] = 1/(s[i]^2),
# can greatly improve convergence.
# 
# IMPRTANT: you should set scale of your variables  with  MinBLEICSetScale()
# call  (before  or after MinBLEICSetPrecScale() call). Without knowledge of
# the scale of your variables scale-based preconditioner will be  just  unit
# matrix.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetprecscale(state)

minbleicsetscale function

#
# This function sets scaling coefficients for BLEIC optimizer.
# 
# ALGLIB optimizers use scaling matrices to test stopping  conditions  (step
# size and gradient are scaled before comparison with tolerances).  Scale of
# the I-th variable is a translation invariant measure of:
# a) "how large" the variable is
# b) how large the step should be to make significant changes in the function
# 
# Scaling is also used by finite difference variant of the optimizer  - step
# along I-th axis is equal to DiffStep*S[I].
# 
# In  most  optimizers  (and  in  the  BLEIC  too)  scaling is NOT a form of
# preconditioning. It just  affects  stopping  conditions.  You  should  set
# preconditioner  by  separate  call  to  one  of  the  MinBLEICSetPrec...()
# functions.
# 
# There is a special  preconditioning  mode, however,  which  uses   scaling
# coefficients to form diagonal preconditioning matrix. You  can  turn  this
# mode on, if you want.   But  you should understand that scaling is not the
# same thing as preconditioning - these are two different, although  related
# forms of tuning solver.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     S       -   array[N], non-zero scaling coefficients
#                 S[i] may be negative, sign doesn't matter.
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetscale(state, s)

minbleicsetstpmax function

#
# This function sets maximum step length
# 
# IMPORTANT: this feature is hard to combine with preconditioning. You can't
# set upper limit on step length, when you solve optimization  problem  with
# linear (non-boundary) constraints AND preconditioner turned on.
# 
# When  non-boundary  constraints  are  present,  you  have to either a) use
# preconditioner, or b) use upper limit on step length.  YOU CAN'T USE BOTH!
# In this case algorithm will terminate with appropriate error code.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     StpMax  -   maximum step length, >=0. Set StpMax to 0.0,  if you don't
#                 want to limit step length.
# 
# Use this subroutine when you optimize target function which contains exp()
# or  other  fast  growing  functions,  and optimization algorithm makes too
# large  steps  which  lead   to overflow. This function allows us to reject
# steps  that  are  too  large  (and  therefore  expose  us  to the possible
# overflow) without actually calculating function value at the x+stp*d.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetstpmax(state, stpmax)

minbleicsetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# If NeedXRep is True, algorithm will call rep() callback function if  it is
# provided to MinBLEICOptimize().
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetxrep(state, needxrep)

minbleic_d_1 example

import xalglib

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# subject to bound constraints -1<=x<=+1, -1<=y<=+1, using BLEIC optimizer.
#
x = [0,0]
bndl = [-1,-1]
bndu = [+1,+1]

#
# These variables define stopping conditions for the optimizer.
#
# We use very simple condition - |g|<=epsg
#
epsg = 0.000001
epsf = 0
epsx = 0
maxits = 0

#
# Now we are ready to actually optimize something:
# * first we create optimizer
# * we add boundary constraints
# * we tune stopping conditions
# * and, finally, optimize and obtain results...
#
state = xalglib.minbleiccreate(x)
xalglib.minbleicsetbc(state, bndl, bndu)
xalglib.minbleicsetcond(state, epsg, epsf, epsx, maxits)
xalglib.minbleicoptimize_g(state, function1_grad)
x, rep = xalglib.minbleicresults(state)

#
# ...and evaluate these results
#
print(rep.terminationtype) # expected 4
print(x) # expected [-1,1]

minbleic_d_2 example

import xalglib

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# subject to inequality constraints:
# * x>=2 (posed as general linear constraint),
# * x+y>=6
# using BLEIC optimizer.
#
x = [5,5]
c = [[1,0,2],[1,1,6]]
ct = [1,1]

#
# These variables define stopping conditions for the optimizer.
#
# We use very simple condition - |g|<=epsg
#
epsg = 0.000001
epsf = 0
epsx = 0
maxits = 0

#
# Now we are ready to actually optimize something:
# * first we create optimizer
# * we add linear constraints
# * we tune stopping conditions
# * and, finally, optimize and obtain results...
#
state = xalglib.minbleiccreate(x)
xalglib.minbleicsetlc(state, c, ct)
xalglib.minbleicsetcond(state, epsg, epsf, epsx, maxits)
xalglib.minbleicoptimize_g(state, function1_grad)
x, rep = xalglib.minbleicresults(state)

#
# ...and evaluate these results
#
print(rep.terminationtype) # expected 4
print(x) # expected [2,4]

minbleic_ftrim example

import xalglib

def s1_grad(x, grad, param):
    #
    # this callback calculates f(x) = (1+x)^(-0.2) + (1-x)^(-0.3) + 1000*x and its gradient.
    #
    # function is trimmed when we calculate it near the singular points or outside of the [-1,+1].
    # Note that we do NOT calculate gradient in this case.
    #
    if (x[0]<=-0.999999999999) or (x[0]>=+0.999999999999):
        return 1.0E+300
    grad[0] = -0.2*math.pow(1+x[0],-1.2) +0.3*math.pow(1-x[0],-1.3) + 1000
    return math.pow(1+x[0],-0.2) + math.pow(1-x[0],-0.3) + 1000*x[0]

#
# This example demonstrates minimization of f(x) = (1+x)^(-0.2) + (1-x)^(-0.3) + 1000*x.
#
# This function is undefined outside of (-1,+1) and has singularities at x=-1 and x=+1.
# Special technique called "function trimming" allows us to solve this optimization problem 
# - without using boundary constraints!
#
# See http://www.alglib.net/optimization/tipsandtricks.php#ftrimming for more information
# on this subject.
#
x = [0]
epsg = 1.0e-6
epsf = 0
epsx = 0
maxits = 0

state = xalglib.minbleiccreate(x)
xalglib.minbleicsetcond(state, epsg, epsf, epsx, maxits)
xalglib.minbleicoptimize_g(state, s1_grad)
x, rep = xalglib.minbleicresults(state)

print(x) # expected [-0.99917305]

minbleic_numdiff example

import xalglib

def function1_func(x, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    #
    return 100*(x[0]+3)**4 + (x[1]-3)**4

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# subject to bound constraints -1<=x<=+1, -1<=y<=+1, using BLEIC optimizer.
#
x = [0,0]
bndl = [-1,-1]
bndu = [+1,+1]

#
# These variables define stopping conditions for the optimizer.
#
# We use very simple condition - |g|<=epsg
#
epsg = 0.000001
epsf = 0
epsx = 0
maxits = 0

#
# This variable contains differentiation step
#
diffstep = 1.0e-6

#
# Now we are ready to actually optimize something:
# * first we create optimizer
# * we add boundary constraints
# * we tune stopping conditions
# * and, finally, optimize and obtain results...
#
state = xalglib.minbleiccreatef(x, diffstep)
xalglib.minbleicsetbc(state, bndl, bndu)
xalglib.minbleicsetcond(state, epsg, epsf, epsx, maxits)
xalglib.minbleicoptimize_f(state, function1_func)
x, rep = xalglib.minbleicresults(state)

#
# ...and evaluate these results
#
print(rep.terminationtype) # expected 4
print(x) # expected [-1,1]

mincg module

mincgreport class

#
# This structure stores optimization report:
# * IterationsCount           total number of inner iterations
# * NFEV                      number of gradient evaluations
# * TerminationType           termination type (see below)
# 
# TERMINATION CODES
# 
# TerminationType field contains completion code, which can be:
#   -8    internal integrity control detected  infinite  or  NAN  values  in
#         function/gradient. Abnormal termination signalled.
#   -7    gradient verification failed.
#         See MinCGSetGradientCheck() for more information.
#    1    relative function improvement is no more than EpsF.
#    2    relative step is no more than EpsX.
#    4    gradient norm is no more than EpsG
#    5    MaxIts steps was taken
#    7    stopping conditions are too stringent,
#         further improvement is impossible,
#         X contains best point found so far.
#    8    terminated by user who called mincgrequesttermination(). X contains
#         point which was "current accepted" when  termination  request  was
#         submitted.
# 
# Other fields of this structure are not documented and should not be used!
#

class mincgreport(object):
    ...

mincgstate class

#
# This object stores state of the nonlinear CG optimizer.
# 
# You should use ALGLIB functions to work with this object.
#

class mincgstate(object):
    ...

mincgcreate function

#
#         NONLINEAR CONJUGATE GRADIENT METHOD
# 
# DESCRIPTION:
# The subroutine minimizes function F(x) of N arguments by using one of  the
# nonlinear conjugate gradient methods.
# 
# These CG methods are globally convergent (even on non-convex functions) as
# long as grad(f) is Lipschitz continuous in  a  some  neighborhood  of  the
# L = { x : f(x)<=f(x0) }.
# 
# 
# REQUIREMENTS:
# Algorithm will request following information during its operation:
# * function value F and its gradient G (simultaneously) at given point X
# 
# 
# USAGE:
# 1. User initializes algorithm state with MinCGCreate() call
# 2. User tunes solver parameters with MinCGSetCond(), MinCGSetStpMax() and
#    other functions
# 3. User calls MinCGOptimize() function which takes algorithm  state   and
#    pointer (delegate, etc.) to callback function which calculates F/G.
# 4. User calls MinCGResults() to get solution
# 5. Optionally, user may call MinCGRestartFrom() to solve another  problem
#    with same N but another starting point and/or another function.
#    MinCGRestartFrom() allows to reuse already initialized structure.
# 
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     X       -   starting point, array[0..N-1].
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 25.03.2010 by Bochkanov Sergey
#

SYNTAX: state = xalglib.mincgcreate(n, x)
SYNTAX: state = xalglib.mincgcreate(x)

Examples:   [1]  [2]  [3]  

mincgcreatef function

#
# The subroutine is finite difference variant of MinCGCreate(). It uses
# finite differences in order to differentiate target function.
# 
# Description below contains information which is specific to this function
# only. We recommend to read comments on MinCGCreate() in order to get more
# information about creation of CG optimizer.
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     X       -   starting point, array[0..N-1].
#     DiffStep-   differentiation step, >0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTES:
# 1. algorithm uses 4-point central formula for differentiation.
# 2. differentiation step along I-th axis is equal to DiffStep*S[I] where
#    S[] is scaling vector which can be set by MinCGSetScale() call.
# 3. we recommend you to use moderate values of  differentiation  step.  Too
#    large step will result in too large truncation  errors, while too small
#    step will result in too large numerical  errors.  1.0E-6  can  be  good
#    value to start with.
# 4. Numerical  differentiation  is   very   inefficient  -   one   gradient
#    calculation needs 4*N function evaluations. This function will work for
#    any N - either small (1...10), moderate (10...100) or  large  (100...).
#    However, performance penalty will be too severe for any N's except  for
#    small ones.
#    We should also say that code which relies on numerical  differentiation
#    is  less  robust  and  precise.  L-BFGS  needs  exact  gradient values.
#    Imprecise  gradient may slow down  convergence,  especially  on  highly
#    nonlinear problems.
#    Thus  we  recommend to use this function for fast prototyping on small-
#    dimensional problems only, and to implement analytical gradient as soon
#    as possible.
# 
#   -- ALGLIB --
#      Copyright 16.05.2011 by Bochkanov Sergey
#

SYNTAX: state = xalglib.mincgcreatef(n, x, diffstep)
SYNTAX: state = xalglib.mincgcreatef(x, diffstep)

Examples:   [1]  

mincgoptimize function

#
# This family of functions is used to launcn iterations of nonlinear optimizer
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     func    -   callback which calculates function (or merit function)
#                 value func at given point x
#     grad    -   callback which calculates function (or merit function)
#                 value func and gradient grad at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# NOTES:
# 
# 1. This function has two different implementations: one which  uses  exact
#    (analytical) user-supplied  gradient, and one which uses function value
#    only  and  numerically  differentiates  function  in  order  to  obtain
#    gradient.
# 
#    Depending  on  the  specific  function  used to create optimizer object
#    (either MinCGCreate()  for analytical gradient  or  MinCGCreateF()  for
#    numerical differentiation) you should  choose  appropriate  variant  of
#    MinCGOptimize() - one which accepts function AND gradient or one  which
#    accepts function ONLY.
# 
#    Be careful to choose variant of MinCGOptimize()  which  corresponds  to
#    your optimization scheme! Table below lists different  combinations  of
#    callback (function/gradient) passed  to  MinCGOptimize()  and  specific
#    function used to create optimizer.
# 
# 
#                   |         USER PASSED TO MinCGOptimize()
#    CREATED WITH   |  function only   |  function and gradient
#    ------------------------------------------------------------
#    MinCGCreateF() |     work                FAIL
#    MinCGCreate()  |     FAIL                work
# 
#    Here "FAIL" denotes inappropriate combinations  of  optimizer  creation
#    function and MinCGOptimize() version. Attemps to use  such  combination
#    (for  example,  to create optimizer with  MinCGCreateF()  and  to  pass
#    gradient information to MinCGOptimize()) will lead to  exception  being
#    thrown. Either  you  did  not  pass  gradient when it WAS needed or you
#    passed gradient when it was NOT needed.
# 
#   -- ALGLIB --
#      Copyright 20.04.2009 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgoptimize_f(state, func, rep = None, param = None)
SYNTAX: xalglib.mincgoptimize_g(state, grad, rep = None, param = None)

Examples:   [1]  [2]  [3]  [4]  

mincgrequesttermination function

#
# This subroutine submits request for termination of running  optimizer.  It
# should be called from user-supplied callback when user decides that it  is
# time to "smoothly" terminate optimization process.  As  result,  optimizer
# stops at point which was "current accepted" when termination  request  was
# submitted and returns error code 8 (successful termination).
# 
# INPUT PARAMETERS:
#     State   -   optimizer structure
# 
# NOTE: after  request  for  termination  optimizer  may   perform   several
#       additional calls to user-supplied callbacks. It does  NOT  guarantee
#       to stop immediately - it just guarantees that these additional calls
#       will be discarded later.
# 
# NOTE: calling this function on optimizer which is NOT running will have no
#       effect.
# 
# NOTE: multiple calls to this function are possible. First call is counted,
#       subsequent calls are silently ignored.
# 
#   -- ALGLIB --
#      Copyright 08.10.2014 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgrequesttermination(state)

mincgrestartfrom function

#
# This  subroutine  restarts  CG  algorithm from new point. All optimization
# parameters are left unchanged.
# 
# This  function  allows  to  solve multiple  optimization  problems  (which
# must have same number of dimensions) without object reallocation penalty.
# 
# INPUT PARAMETERS:
#     State   -   structure used to store algorithm state.
#     X       -   new starting point.
# 
#   -- ALGLIB --
#      Copyright 30.07.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgrestartfrom(state, x)

Examples:   [1]  

mincgresults function

#
# Conjugate gradient results
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[0..N-1], solution
#     Rep     -   optimization report:
#                 * Rep.TerminationType completetion code:
#                     * -8    internal integrity control  detected  infinite
#                             or NAN values in  function/gradient.  Abnormal
#                             termination signalled.
#                     * -7    gradient verification failed.
#                             See MinCGSetGradientCheck() for more information.
#                     *  1    relative function improvement is no more than
#                             EpsF.
#                     *  2    relative step is no more than EpsX.
#                     *  4    gradient norm is no more than EpsG
#                     *  5    MaxIts steps was taken
#                     *  7    stopping conditions are too stringent,
#                             further improvement is impossible,
#                             we return best X found so far
#                     *  8    terminated by user
#                 * Rep.IterationsCount contains iterations count
#                 * NFEV countains number of function calculations
# 
#   -- ALGLIB --
#      Copyright 20.04.2009 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.mincgresults(state)

Examples:   [1]  [2]  [3]  [4]  

mincgresultsbuf function

#
# Conjugate gradient results
# 
# Buffered implementation of MinCGResults(), which uses pre-allocated buffer
# to store X[]. If buffer size is  too  small,  it  resizes  buffer.  It  is
# intended to be used in the inner cycles of performance critical algorithms
# where array reallocation penalty is too large to be ignored.
# 
#   -- ALGLIB --
#      Copyright 20.04.2009 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.mincgresultsbuf(state, x, rep)

mincgsetcgtype function

#
# This function sets CG algorithm.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     CGType  -   algorithm type:
#                 * -1    automatic selection of the best algorithm
#                 * 0     DY (Dai and Yuan) algorithm
#                 * 1     Hybrid DY-HS algorithm
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetcgtype(state, cgtype)

mincgsetcond function

#
# This function sets stopping conditions for CG optimization algorithm.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     EpsG    -   >=0
#                 The  subroutine  finishes  its  work   if   the  condition
#                 |v|<EpsG is satisfied, where:
#                 * |.| means Euclidian norm
#                 * v - scaled gradient vector, v[i]=g[i]*s[i]
#                 * g - gradient
#                 * s - scaling coefficients set by MinCGSetScale()
#     EpsF    -   >=0
#                 The  subroutine  finishes  its work if on k+1-th iteration
#                 the  condition  |F(k+1)-F(k)|<=EpsF*max{|F(k)|,|F(k+1)|,1}
#                 is satisfied.
#     EpsX    -   >=0
#                 The subroutine finishes its work if  on  k+1-th  iteration
#                 the condition |v|<=EpsX is fulfilled, where:
#                 * |.| means Euclidian norm
#                 * v - scaled step vector, v[i]=dx[i]/s[i]
#                 * dx - ste pvector, dx=X(k+1)-X(k)
#                 * s - scaling coefficients set by MinCGSetScale()
#     MaxIts  -   maximum number of iterations. If MaxIts=0, the  number  of
#                 iterations is unlimited.
# 
# Passing EpsG=0, EpsF=0, EpsX=0 and MaxIts=0 (simultaneously) will lead to
# automatic stopping criterion selection (small EpsX).
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetcond(state, epsg, epsf, epsx, maxits)

Examples:   [1]  [2]  [3]  

mincgsetgradientcheck function

#
# 
# This  subroutine  turns  on  verification  of  the  user-supplied analytic
# gradient:
# * user calls this subroutine before optimization begins
# * MinCGOptimize() is called
# * prior to  actual  optimization, for each component  of  parameters being
#   optimized X[i] algorithm performs following steps:
#   * two trial steps are made to X[i]-TestStep*S[i] and X[i]+TestStep*S[i],
#     where X[i] is i-th component of the initial point and S[i] is a  scale
#     of i-th parameter
#   * F(X) is evaluated at these trial points
#   * we perform one more evaluation in the middle point of the interval
#   * we  build  cubic  model using function values and derivatives at trial
#     points and we compare its prediction with actual value in  the  middle
#     point
#   * in case difference between prediction and actual value is higher  than
#     some predetermined threshold, algorithm stops with completion code -7;
#     Rep.VarIdx is set to index of the parameter with incorrect derivative.
# * after verification is over, algorithm proceeds to the actual optimization.
# 
# NOTE 1: verification  needs  N (parameters count) gradient evaluations. It
#         is very costly and you should use  it  only  for  low  dimensional
#         problems,  when  you  want  to  be  sure  that  you've   correctly
#         calculated  analytic  derivatives.  You  should  not use it in the
#         production code (unless you want to check derivatives provided  by
#         some third party).
# 
# NOTE 2: you  should  carefully  choose  TestStep. Value which is too large
#         (so large that function behaviour is significantly non-cubic) will
#         lead to false alarms. You may use  different  step  for  different
#         parameters by means of setting scale with MinCGSetScale().
# 
# NOTE 3: this function may lead to false positives. In case it reports that
#         I-th  derivative was calculated incorrectly, you may decrease test
#         step  and  try  one  more  time  - maybe your function changes too
#         sharply  and  your  step  is  too  large for such rapidly chanding
#         function.
# 
# INPUT PARAMETERS:
#     State       -   structure used to store algorithm state
#     TestStep    -   verification step:
#                     * TestStep=0 turns verification off
#                     * TestStep>0 activates verification
# 
#   -- ALGLIB --
#      Copyright 31.05.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetgradientcheck(state, teststep)

mincgsetprecdefault function

#
# Modification of the preconditioner: preconditioning is turned off.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTE:  you  can  change  preconditioner  "on  the  fly",  during algorithm
# iterations.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetprecdefault(state)

mincgsetprecdiag function

#
# Modification  of  the  preconditioner:  diagonal of approximate Hessian is
# used.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     D       -   diagonal of the approximate Hessian, array[0..N-1],
#                 (if larger, only leading N elements are used).
# 
# NOTE:  you  can  change  preconditioner  "on  the  fly",  during algorithm
# iterations.
# 
# NOTE 2: D[i] should be positive. Exception will be thrown otherwise.
# 
# NOTE 3: you should pass diagonal of approximate Hessian - NOT ITS INVERSE.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetprecdiag(state, d)

mincgsetprecscale function

#
# Modification of the preconditioner: scale-based diagonal preconditioning.
# 
# This preconditioning mode can be useful when you  don't  have  approximate
# diagonal of Hessian, but you know that your  variables  are  badly  scaled
# (for  example,  one  variable is in [1,10], and another in [1000,100000]),
# and most part of the ill-conditioning comes from different scales of vars.
# 
# In this case simple  scale-based  preconditioner,  with H[i] = 1/(s[i]^2),
# can greatly improve convergence.
# 
# IMPRTANT: you should set scale of your variables with MinCGSetScale() call
# (before or after MinCGSetPrecScale() call). Without knowledge of the scale
# of your variables scale-based preconditioner will be just unit matrix.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTE:  you  can  change  preconditioner  "on  the  fly",  during algorithm
# iterations.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetprecscale(state)

mincgsetscale function

#
# This function sets scaling coefficients for CG optimizer.
# 
# ALGLIB optimizers use scaling matrices to test stopping  conditions  (step
# size and gradient are scaled before comparison with tolerances).  Scale of
# the I-th variable is a translation invariant measure of:
# a) "how large" the variable is
# b) how large the step should be to make significant changes in the function
# 
# Scaling is also used by finite difference variant of CG optimizer  -  step
# along I-th axis is equal to DiffStep*S[I].
# 
# In   most   optimizers  (and  in  the  CG  too)  scaling is NOT a form  of
# preconditioning. It just  affects  stopping  conditions.  You  should  set
# preconditioner by separate call to one of the MinCGSetPrec...() functions.
# 
# There  is  special  preconditioning  mode, however,  which  uses   scaling
# coefficients to form diagonal preconditioning matrix. You  can  turn  this
# mode on, if you want.   But  you should understand that scaling is not the
# same thing as preconditioning - these are two different, although  related
# forms of tuning solver.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     S       -   array[N], non-zero scaling coefficients
#                 S[i] may be negative, sign doesn't matter.
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetscale(state, s)

mincgsetstpmax function

#
# This function sets maximum step length
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     StpMax  -   maximum step length, >=0. Set StpMax to 0.0,  if you don't
#                 want to limit step length.
# 
# Use this subroutine when you optimize target function which contains exp()
# or  other  fast  growing  functions,  and optimization algorithm makes too
# large  steps  which  leads  to overflow. This function allows us to reject
# steps  that  are  too  large  (and  therefore  expose  us  to the possible
# overflow) without actually calculating function value at the x+stp*d.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetstpmax(state, stpmax)

mincgsetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# If NeedXRep is True, algorithm will call rep() callback function if  it is
# provided to MinCGOptimize().
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsetxrep(state, needxrep)

mincgsuggeststep function

#
# This function allows to suggest initial step length to the CG algorithm.
# 
# Suggested  step  length  is used as starting point for the line search. It
# can be useful when you have  badly  scaled  problem,  i.e.  when  ||grad||
# (which is used as initial estimate for the first step) is many  orders  of
# magnitude different from the desired step.
# 
# Line search  may  fail  on  such problems without good estimate of initial
# step length. Imagine, for example, problem with ||grad||=10^50 and desired
# step equal to 0.1 Line  search function will use 10^50  as  initial  step,
# then  it  will  decrease step length by 2 (up to 20 attempts) and will get
# 10^44, which is still too large.
# 
# This function allows us to tell than line search should  be  started  from
# some moderate step length, like 1.0, so algorithm will be able  to  detect
# desired step length in a several searches.
# 
# Default behavior (when no step is suggested) is to use preconditioner,  if
# it is available, to generate initial estimate of step length.
# 
# This function influences only first iteration of algorithm. It  should  be
# called between MinCGCreate/MinCGRestartFrom() call and MinCGOptimize call.
# Suggested step is ignored if you have preconditioner.
# 
# INPUT PARAMETERS:
#     State   -   structure used to store algorithm state.
#     Stp     -   initial estimate of the step length.
#                 Can be zero (no estimate).
# 
#   -- ALGLIB --
#      Copyright 30.07.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.mincgsuggeststep(state, stp)

mincg_d_1 example

import xalglib

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# with nonlinear conjugate gradient method.
#
x = [0,0]
epsg = 0.0000000001
epsf = 0
epsx = 0
maxits = 0

state = xalglib.mincgcreate(x)
xalglib.mincgsetcond(state, epsg, epsf, epsx, maxits)
xalglib.mincgoptimize_g(state, function1_grad)
x, rep = xalglib.mincgresults(state)

print(rep.terminationtype) # expected 4
print(x) # expected [-3,3]

mincg_d_2 example

import xalglib

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# with nonlinear conjugate gradient method.
#
# Several advanced techniques are demonstrated:
# * upper limit on step size
# * restart from new point
#
x = [0,0]
epsg = 0.0000000001
epsf = 0
epsx = 0
stpmax = 0.1
maxits = 0

# first run
state = xalglib.mincgcreate(x)
xalglib.mincgsetcond(state, epsg, epsf, epsx, maxits)
xalglib.mincgsetstpmax(state, stpmax)
xalglib.mincgoptimize_g(state, function1_grad)
x, rep = xalglib.mincgresults(state)

print(x) # expected [-3,3]

# second run - algorithm is restarted with mincgrestartfrom()
x = [10,10]
xalglib.mincgrestartfrom(state, x)
xalglib.mincgoptimize_g(state, function1_grad)
x, rep = xalglib.mincgresults(state)

print(rep.terminationtype) # expected 4
print(x) # expected [-3,3]

mincg_ftrim example

import xalglib

def s1_grad(x, grad, param):
    #
    # this callback calculates f(x) = (1+x)^(-0.2) + (1-x)^(-0.3) + 1000*x and its gradient.
    #
    # function is trimmed when we calculate it near the singular points or outside of the [-1,+1].
    # Note that we do NOT calculate gradient in this case.
    #
    if (x[0]<=-0.999999999999) or (x[0]>=+0.999999999999):
        return 1.0E+300
    grad[0] = -0.2*math.pow(1+x[0],-1.2) +0.3*math.pow(1-x[0],-1.3) + 1000
    return math.pow(1+x[0],-0.2) + math.pow(1-x[0],-0.3) + 1000*x[0]

#
# This example demonstrates minimization of f(x) = (1+x)^(-0.2) + (1-x)^(-0.3) + 1000*x.
# This function has singularities at the boundary of the [-1,+1], but technique called
# "function trimming" allows us to solve this optimization problem.
#
# See http://www.alglib.net/optimization/tipsandtricks.php#ftrimming for more information
# on this subject.
#
x = [0]
epsg = 1.0e-6
epsf = 0
epsx = 0
maxits = 0

state = xalglib.mincgcreate(x)
xalglib.mincgsetcond(state, epsg, epsf, epsx, maxits)
xalglib.mincgoptimize_g(state, s1_grad)
x, rep = xalglib.mincgresults(state)

print(x) # expected [-0.99917305]

mincg_numdiff example

import xalglib

def function1_func(x, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    #
    return 100*(x[0]+3)**4 + (x[1]-3)**4

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# using numerical differentiation to calculate gradient.
#
x = [0,0]
epsg = 0.0000000001
epsf = 0
epsx = 0
diffstep = 1.0e-6
maxits = 0

state = xalglib.mincgcreatef(x, diffstep)
xalglib.mincgsetcond(state, epsg, epsf, epsx, maxits)
xalglib.mincgoptimize_f(state, function1_func)
x, rep = xalglib.mincgresults(state)

print(rep.terminationtype) # expected 4
print(x) # expected [-3,3]

mincomp module

minasareport class

#
# 
#

class minasareport(object):
    ...

minasastate class

#
# 
#

class minasastate(object):
    ...

minasacreate function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 25.03.2010 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minasacreate(n, x, bndl, bndu)
SYNTAX: state = xalglib.minasacreate(x, bndl, bndu)

minasaoptimize function

#
# This family of functions is used to launcn iterations of nonlinear optimizer
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     grad    -   callback which calculates function (or merit function)
#                 value func and gradient grad at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# 
#   -- ALGLIB --
#      Copyright 20.03.2009 by Bochkanov Sergey
#

SYNTAX: xalglib.minasaoptimize_g(state, grad, rep = None, param = None)

minasarestartfrom function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 30.07.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minasarestartfrom(state, x, bndl, bndu)

minasaresults function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 20.03.2009 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minasaresults(state)

minasaresultsbuf function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 20.03.2009 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minasaresultsbuf(state, x, rep)

minasasetalgorithm function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minasasetalgorithm(state, algotype)

minasasetcond function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minasasetcond(state, epsg, epsf, epsx, maxits)

minasasetstpmax function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minasasetstpmax(state, stpmax)

minasasetxrep function

#
# Obsolete optimization algorithm.
# Was replaced by MinBLEIC subpackage.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minasasetxrep(state, needxrep)

minbleicsetbarrierdecay function

#
# This is obsolete function which was used by previous version of the  BLEIC
# optimizer. It does nothing in the current version of BLEIC.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetbarrierdecay(state, mudecay)

minbleicsetbarrierwidth function

#
# This is obsolete function which was used by previous version of the  BLEIC
# optimizer. It does nothing in the current version of BLEIC.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minbleicsetbarrierwidth(state, mu)

minlbfgssetcholeskypreconditioner function

#
# Obsolete function, use MinLBFGSSetCholeskyPreconditioner() instead.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetcholeskypreconditioner(state, p, isupper)

minlbfgssetdefaultpreconditioner function

#
# Obsolete function, use MinLBFGSSetPrecDefault() instead.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetdefaultpreconditioner(state)

minlbfgs module

minlbfgsreport class

#
# This structure stores optimization report:
# * IterationsCount           total number of inner iterations
# * NFEV                      number of gradient evaluations
# * TerminationType           termination type (see below)
# 
# TERMINATION CODES
# 
# TerminationType field contains completion code, which can be:
#   -8    internal integrity control detected  infinite  or  NAN  values  in
#         function/gradient. Abnormal termination signalled.
#   -7    gradient verification failed.
#         See MinLBFGSSetGradientCheck() for more information.
#    1    relative function improvement is no more than EpsF.
#    2    relative step is no more than EpsX.
#    4    gradient norm is no more than EpsG
#    5    MaxIts steps was taken
#    7    stopping conditions are too stringent,
#         further improvement is impossible,
#         X contains best point found so far.
#    8    terminated    by  user  who  called  minlbfgsrequesttermination().
#         X contains point which was   "current accepted"  when  termination
#         request was submitted.
# 
# Other fields of this structure are not documented and should not be used!
#

class minlbfgsreport(object):
    ...

minlbfgsstate class

#
# 
#

class minlbfgsstate(object):
    ...

minlbfgscreate function

#
#         LIMITED MEMORY BFGS METHOD FOR LARGE SCALE OPTIMIZATION
# 
# DESCRIPTION:
# The subroutine minimizes function F(x) of N arguments by  using  a  quasi-
# Newton method (LBFGS scheme) which is optimized to use  a  minimum  amount
# of memory.
# The subroutine generates the approximation of an inverse Hessian matrix by
# using information about the last M steps of the algorithm  (instead of N).
# It lessens a required amount of memory from a value  of  order  N^2  to  a
# value of order 2*N*M.
# 
# 
# REQUIREMENTS:
# Algorithm will request following information during its operation:
# * function value F and its gradient G (simultaneously) at given point X
# 
# 
# USAGE:
# 1. User initializes algorithm state with MinLBFGSCreate() call
# 2. User tunes solver parameters with MinLBFGSSetCond() MinLBFGSSetStpMax()
#    and other functions
# 3. User calls MinLBFGSOptimize() function which takes algorithm  state and
#    pointer (delegate, etc.) to callback function which calculates F/G.
# 4. User calls MinLBFGSResults() to get solution
# 5. Optionally user may call MinLBFGSRestartFrom() to solve another problem
#    with same N/M but another starting point and/or another function.
#    MinLBFGSRestartFrom() allows to reuse already initialized structure.
# 
# 
# INPUT PARAMETERS:
#     N       -   problem dimension. N>0
#     M       -   number of corrections in the BFGS scheme of Hessian
#                 approximation update. Recommended value:  3<=M<=7. The smaller
#                 value causes worse convergence, the bigger will  not  cause  a
#                 considerably better convergence, but will cause a fall in  the
#                 performance. M<=N.
#     X       -   initial solution approximation, array[0..N-1].
# 
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# 
# NOTES:
# 1. you may tune stopping conditions with MinLBFGSSetCond() function
# 2. if target function contains exp() or other fast growing functions,  and
#    optimization algorithm makes too large steps which leads  to  overflow,
#    use MinLBFGSSetStpMax() function to bound algorithm's  steps.  However,
#    L-BFGS rarely needs such a tuning.
# 
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlbfgscreate(n, m, x)
SYNTAX: state = xalglib.minlbfgscreate(m, x)

Examples:   [1]  [2]  [3]  

minlbfgscreatef function

#
# The subroutine is finite difference variant of MinLBFGSCreate().  It  uses
# finite differences in order to differentiate target function.
# 
# Description below contains information which is specific to  this function
# only. We recommend to read comments on MinLBFGSCreate() in  order  to  get
# more information about creation of LBFGS optimizer.
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     M       -   number of corrections in the BFGS scheme of Hessian
#                 approximation update. Recommended value:  3<=M<=7. The smaller
#                 value causes worse convergence, the bigger will  not  cause  a
#                 considerably better convergence, but will cause a fall in  the
#                 performance. M<=N.
#     X       -   starting point, array[0..N-1].
#     DiffStep-   differentiation step, >0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTES:
# 1. algorithm uses 4-point central formula for differentiation.
# 2. differentiation step along I-th axis is equal to DiffStep*S[I] where
#    S[] is scaling vector which can be set by MinLBFGSSetScale() call.
# 3. we recommend you to use moderate values of  differentiation  step.  Too
#    large step will result in too large truncation  errors, while too small
#    step will result in too large numerical  errors.  1.0E-6  can  be  good
#    value to start with.
# 4. Numerical  differentiation  is   very   inefficient  -   one   gradient
#    calculation needs 4*N function evaluations. This function will work for
#    any N - either small (1...10), moderate (10...100) or  large  (100...).
#    However, performance penalty will be too severe for any N's except  for
#    small ones.
#    We should also say that code which relies on numerical  differentiation
#    is   less  robust  and  precise.  LBFGS  needs  exact  gradient values.
#    Imprecise gradient may slow  down  convergence,  especially  on  highly
#    nonlinear problems.
#    Thus  we  recommend to use this function for fast prototyping on small-
#    dimensional problems only, and to implement analytical gradient as soon
#    as possible.
# 
#   -- ALGLIB --
#      Copyright 16.05.2011 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlbfgscreatef(n, m, x, diffstep)
SYNTAX: state = xalglib.minlbfgscreatef(m, x, diffstep)

Examples:   [1]  

minlbfgsoptimize function

#
# This family of functions is used to launcn iterations of nonlinear optimizer
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     func    -   callback which calculates function (or merit function)
#                 value func at given point x
#     grad    -   callback which calculates function (or merit function)
#                 value func and gradient grad at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# NOTES:
# 
# 1. This function has two different implementations: one which  uses  exact
#    (analytical) user-supplied gradient,  and one which uses function value
#    only  and  numerically  differentiates  function  in  order  to  obtain
#    gradient.
# 
#    Depending  on  the  specific  function  used to create optimizer object
#    (either MinLBFGSCreate() for analytical gradient  or  MinLBFGSCreateF()
#    for numerical differentiation) you should choose appropriate variant of
#    MinLBFGSOptimize() - one  which  accepts  function  AND gradient or one
#    which accepts function ONLY.
# 
#    Be careful to choose variant of MinLBFGSOptimize() which corresponds to
#    your optimization scheme! Table below lists different  combinations  of
#    callback (function/gradient) passed to MinLBFGSOptimize()  and specific
#    function used to create optimizer.
# 
# 
#                      |         USER PASSED TO MinLBFGSOptimize()
#    CREATED WITH      |  function only   |  function and gradient
#    ------------------------------------------------------------
#    MinLBFGSCreateF() |     work                FAIL
#    MinLBFGSCreate()  |     FAIL                work
# 
#    Here "FAIL" denotes inappropriate combinations  of  optimizer  creation
#    function  and  MinLBFGSOptimize()  version.   Attemps   to   use   such
#    combination (for example, to create optimizer with MinLBFGSCreateF() and
#    to pass gradient information to MinCGOptimize()) will lead to exception
#    being thrown. Either  you  did  not pass gradient when it WAS needed or
#    you passed gradient when it was NOT needed.
# 
#   -- ALGLIB --
#      Copyright 20.03.2009 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgsoptimize_f(state, func, rep = None, param = None)
SYNTAX: xalglib.minlbfgsoptimize_g(state, grad, rep = None, param = None)

Examples:   [1]  [2]  [3]  [4]  

minlbfgsrequesttermination function

#
# This subroutine submits request for termination of running  optimizer.  It
# should be called from user-supplied callback when user decides that it  is
# time to "smoothly" terminate optimization process.  As  result,  optimizer
# stops at point which was "current accepted" when termination  request  was
# submitted and returns error code 8 (successful termination).
# 
# INPUT PARAMETERS:
#     State   -   optimizer structure
# 
# NOTE: after  request  for  termination  optimizer  may   perform   several
#       additional calls to user-supplied callbacks. It does  NOT  guarantee
#       to stop immediately - it just guarantees that these additional calls
#       will be discarded later.
# 
# NOTE: calling this function on optimizer which is NOT running will have no
#       effect.
# 
# NOTE: multiple calls to this function are possible. First call is counted,
#       subsequent calls are silently ignored.
# 
#   -- ALGLIB --
#      Copyright 08.10.2014 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgsrequesttermination(state)

minlbfgsrestartfrom function

#
# This  subroutine restarts LBFGS algorithm from new point. All optimization
# parameters are left unchanged.
# 
# This  function  allows  to  solve multiple  optimization  problems  (which
# must have same number of dimensions) without object reallocation penalty.
# 
# INPUT PARAMETERS:
#     State   -   structure used to store algorithm state
#     X       -   new starting point.
# 
#   -- ALGLIB --
#      Copyright 30.07.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgsrestartfrom(state, x)

Examples:   [1]  

minlbfgsresults function

#
# L-BFGS algorithm results
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[0..N-1], solution
#     Rep     -   optimization report:
#                 * Rep.TerminationType completetion code:
#                     * -8    internal integrity control  detected  infinite
#                             or NAN values in  function/gradient.  Abnormal
#                             termination signalled.
#                     * -7    gradient verification failed.
#                             See MinLBFGSSetGradientCheck() for more information.
#                     * -2    rounding errors prevent further improvement.
#                             X contains best point found.
#                     * -1    incorrect parameters were specified
#                     *  1    relative function improvement is no more than
#                             EpsF.
#                     *  2    relative step is no more than EpsX.
#                     *  4    gradient norm is no more than EpsG
#                     *  5    MaxIts steps was taken
#                     *  7    stopping conditions are too stringent,
#                             further improvement is impossible
#                     *  8    terminated by user who called minlbfgsrequesttermination().
#                             X contains point which was "current accepted" when
#                             termination request was submitted.
#                 * Rep.IterationsCount contains iterations count
#                 * NFEV countains number of function calculations
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minlbfgsresults(state)

Examples:   [1]  [2]  [3]  [4]  

minlbfgsresultsbuf function

#
# L-BFGS algorithm results
# 
# Buffered implementation of MinLBFGSResults which uses pre-allocated buffer
# to store X[]. If buffer size is  too  small,  it  resizes  buffer.  It  is
# intended to be used in the inner cycles of performance critical algorithms
# where array reallocation penalty is too large to be ignored.
# 
#   -- ALGLIB --
#      Copyright 20.08.2010 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minlbfgsresultsbuf(state, x, rep)

minlbfgssetcond function

#
# This function sets stopping conditions for L-BFGS optimization algorithm.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     EpsG    -   >=0
#                 The  subroutine  finishes  its  work   if   the  condition
#                 |v|<EpsG is satisfied, where:
#                 * |.| means Euclidian norm
#                 * v - scaled gradient vector, v[i]=g[i]*s[i]
#                 * g - gradient
#                 * s - scaling coefficients set by MinLBFGSSetScale()
#     EpsF    -   >=0
#                 The  subroutine  finishes  its work if on k+1-th iteration
#                 the  condition  |F(k+1)-F(k)|<=EpsF*max{|F(k)|,|F(k+1)|,1}
#                 is satisfied.
#     EpsX    -   >=0
#                 The subroutine finishes its work if  on  k+1-th  iteration
#                 the condition |v|<=EpsX is fulfilled, where:
#                 * |.| means Euclidian norm
#                 * v - scaled step vector, v[i]=dx[i]/s[i]
#                 * dx - ste pvector, dx=X(k+1)-X(k)
#                 * s - scaling coefficients set by MinLBFGSSetScale()
#     MaxIts  -   maximum number of iterations. If MaxIts=0, the  number  of
#                 iterations is unlimited.
# 
# Passing EpsG=0, EpsF=0, EpsX=0 and MaxIts=0 (simultaneously) will lead to
# automatic stopping criterion selection (small EpsX).
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetcond(state, epsg, epsf, epsx, maxits)

Examples:   [1]  [2]  [3]  

minlbfgssetgradientcheck function

#
# This  subroutine  turns  on  verification  of  the  user-supplied analytic
# gradient:
# * user calls this subroutine before optimization begins
# * MinLBFGSOptimize() is called
# * prior to  actual  optimization, for each component  of  parameters being
#   optimized X[i] algorithm performs following steps:
#   * two trial steps are made to X[i]-TestStep*S[i] and X[i]+TestStep*S[i],
#     where X[i] is i-th component of the initial point and S[i] is a  scale
#     of i-th parameter
#   * if needed, steps are bounded with respect to constraints on X[]
#   * F(X) is evaluated at these trial points
#   * we perform one more evaluation in the middle point of the interval
#   * we  build  cubic  model using function values and derivatives at trial
#     points and we compare its prediction with actual value in  the  middle
#     point
#   * in case difference between prediction and actual value is higher  than
#     some predetermined threshold, algorithm stops with completion code -7;
#     Rep.VarIdx is set to index of the parameter with incorrect derivative.
# * after verification is over, algorithm proceeds to the actual optimization.
# 
# NOTE 1: verification  needs  N (parameters count) gradient evaluations. It
#         is very costly and you should use  it  only  for  low  dimensional
#         problems,  when  you  want  to  be  sure  that  you've   correctly
#         calculated  analytic  derivatives.  You  should  not use it in the
#         production code (unless you want to check derivatives provided  by
#         some third party).
# 
# NOTE 2: you  should  carefully  choose  TestStep. Value which is too large
#         (so large that function behaviour is significantly non-cubic) will
#         lead to false alarms. You may use  different  step  for  different
#         parameters by means of setting scale with MinLBFGSSetScale().
# 
# NOTE 3: this function may lead to false positives. In case it reports that
#         I-th  derivative was calculated incorrectly, you may decrease test
#         step  and  try  one  more  time  - maybe your function changes too
#         sharply  and  your  step  is  too  large for such rapidly chanding
#         function.
# 
# INPUT PARAMETERS:
#     State       -   structure used to store algorithm state
#     TestStep    -   verification step:
#                     * TestStep=0 turns verification off
#                     * TestStep>0 activates verification
# 
#   -- ALGLIB --
#      Copyright 24.05.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetgradientcheck(state, teststep)

minlbfgssetpreccholesky function

#
# Modification of the preconditioner: Cholesky factorization of  approximate
# Hessian is used.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     P       -   triangular preconditioner, Cholesky factorization of
#                 the approximate Hessian. array[0..N-1,0..N-1],
#                 (if larger, only leading N elements are used).
#     IsUpper -   whether upper or lower triangle of P is given
#                 (other triangle is not referenced)
# 
# After call to this function preconditioner is changed to P  (P  is  copied
# into the internal buffer).
# 
# NOTE:  you  can  change  preconditioner  "on  the  fly",  during algorithm
# iterations.
# 
# NOTE 2:  P  should  be nonsingular. Exception will be thrown otherwise.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetpreccholesky(state, p, isupper)

minlbfgssetprecdefault function

#
# Modification  of  the  preconditioner:  default  preconditioner    (simple
# scaling, same for all elements of X) is used.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTE:  you  can  change  preconditioner  "on  the  fly",  during algorithm
# iterations.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetprecdefault(state)

minlbfgssetprecdiag function

#
# Modification  of  the  preconditioner:  diagonal of approximate Hessian is
# used.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     D       -   diagonal of the approximate Hessian, array[0..N-1],
#                 (if larger, only leading N elements are used).
# 
# NOTE:  you  can  change  preconditioner  "on  the  fly",  during algorithm
# iterations.
# 
# NOTE 2: D[i] should be positive. Exception will be thrown otherwise.
# 
# NOTE 3: you should pass diagonal of approximate Hessian - NOT ITS INVERSE.
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetprecdiag(state, d)

minlbfgssetprecscale function

#
# Modification of the preconditioner: scale-based diagonal preconditioning.
# 
# This preconditioning mode can be useful when you  don't  have  approximate
# diagonal of Hessian, but you know that your  variables  are  badly  scaled
# (for  example,  one  variable is in [1,10], and another in [1000,100000]),
# and most part of the ill-conditioning comes from different scales of vars.
# 
# In this case simple  scale-based  preconditioner,  with H[i] = 1/(s[i]^2),
# can greatly improve convergence.
# 
# IMPRTANT: you should set scale of your variables  with  MinLBFGSSetScale()
# call  (before  or after MinLBFGSSetPrecScale() call). Without knowledge of
# the scale of your variables scale-based preconditioner will be  just  unit
# matrix.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 13.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetprecscale(state)

minlbfgssetscale function

#
# This function sets scaling coefficients for LBFGS optimizer.
# 
# ALGLIB optimizers use scaling matrices to test stopping  conditions  (step
# size and gradient are scaled before comparison with tolerances).  Scale of
# the I-th variable is a translation invariant measure of:
# a) "how large" the variable is
# b) how large the step should be to make significant changes in the function
# 
# Scaling is also used by finite difference variant of the optimizer  - step
# along I-th axis is equal to DiffStep*S[I].
# 
# In  most  optimizers  (and  in  the  LBFGS  too)  scaling is NOT a form of
# preconditioning. It just  affects  stopping  conditions.  You  should  set
# preconditioner  by  separate  call  to  one  of  the  MinLBFGSSetPrec...()
# functions.
# 
# There  is  special  preconditioning  mode, however,  which  uses   scaling
# coefficients to form diagonal preconditioning matrix. You  can  turn  this
# mode on, if you want.   But  you should understand that scaling is not the
# same thing as preconditioning - these are two different, although  related
# forms of tuning solver.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     S       -   array[N], non-zero scaling coefficients
#                 S[i] may be negative, sign doesn't matter.
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetscale(state, s)

minlbfgssetstpmax function

#
# This function sets maximum step length
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     StpMax  -   maximum step length, >=0. Set StpMax to 0.0 (default),  if
#                 you don't want to limit step length.
# 
# Use this subroutine when you optimize target function which contains exp()
# or  other  fast  growing  functions,  and optimization algorithm makes too
# large  steps  which  leads  to overflow. This function allows us to reject
# steps  that  are  too  large  (and  therefore  expose  us  to the possible
# overflow) without actually calculating function value at the x+stp*d.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetstpmax(state, stpmax)

minlbfgssetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# If NeedXRep is True, algorithm will call rep() callback function if  it is
# provided to MinLBFGSOptimize().
# 
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlbfgssetxrep(state, needxrep)

minlbfgs_d_1 example

import xalglib

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# using LBFGS method.
#
x = [0,0]
epsg = 0.0000000001
epsf = 0
epsx = 0
maxits = 0

state = xalglib.minlbfgscreate(1, x)
xalglib.minlbfgssetcond(state, epsg, epsf, epsx, maxits)
xalglib.minlbfgsoptimize_g(state, function1_grad)
x, rep = xalglib.minlbfgsresults(state)

print(rep.terminationtype) # expected 4
print(x) # expected [-3,3]

minlbfgs_d_2 example

import xalglib

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# using LBFGS method.
#
# Several advanced techniques are demonstrated:
# * upper limit on step size
# * restart from new point
#
x = [0,0]
epsg = 0.0000000001
epsf = 0
epsx = 0
stpmax = 0.1
maxits = 0

# first run
state = xalglib.minlbfgscreate(1, x)
xalglib.minlbfgssetcond(state, epsg, epsf, epsx, maxits)
xalglib.minlbfgssetstpmax(state, stpmax)
xalglib.minlbfgsoptimize_g(state, function1_grad)
x, rep = xalglib.minlbfgsresults(state)

print(x) # expected [-3,3]

# second run - algorithm is restarted
x = [10,10]
xalglib.minlbfgsrestartfrom(state, x)
xalglib.minlbfgsoptimize_g(state, function1_grad)
x, rep = xalglib.minlbfgsresults(state)

print(rep.terminationtype) # expected 4
print(x) # expected [-3,3]

minlbfgs_ftrim example

import xalglib

def s1_grad(x, grad, param):
    #
    # this callback calculates f(x) = (1+x)^(-0.2) + (1-x)^(-0.3) + 1000*x and its gradient.
    #
    # function is trimmed when we calculate it near the singular points or outside of the [-1,+1].
    # Note that we do NOT calculate gradient in this case.
    #
    if (x[0]<=-0.999999999999) or (x[0]>=+0.999999999999):
        return 1.0E+300
    grad[0] = -0.2*math.pow(1+x[0],-1.2) +0.3*math.pow(1-x[0],-1.3) + 1000
    return math.pow(1+x[0],-0.2) + math.pow(1-x[0],-0.3) + 1000*x[0]

#
# This example demonstrates minimization of f(x) = (1+x)^(-0.2) + (1-x)^(-0.3) + 1000*x.
# This function has singularities at the boundary of the [-1,+1], but technique called
# "function trimming" allows us to solve this optimization problem.
#
# See http://www.alglib.net/optimization/tipsandtricks.php#ftrimming for more information
# on this subject.
#
x = [0]
epsg = 1.0e-6
epsf = 0
epsx = 0
maxits = 0

state = xalglib.minlbfgscreate(1, x)
xalglib.minlbfgssetcond(state, epsg, epsf, epsx, maxits)
xalglib.minlbfgsoptimize_g(state, s1_grad)
x, rep = xalglib.minlbfgsresults(state)

print(x) # expected [-0.99917305]

minlbfgs_numdiff example

import xalglib

def function1_func(x, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    #
    return 100*(x[0]+3)**4 + (x[1]-3)**4

#
# This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4
# using numerical differentiation to calculate gradient.
#
x = [0,0]
epsg = 0.0000000001
epsf = 0
epsx = 0
diffstep = 1.0e-6
maxits = 0

state = xalglib.minlbfgscreatef(1, x, diffstep)
xalglib.minlbfgssetcond(state, epsg, epsf, epsx, maxits)
xalglib.minlbfgsoptimize_f(state, function1_func)
x, rep = xalglib.minlbfgsresults(state)

print(rep.terminationtype) # expected 4
print(x) # expected [-3,3]

minlm module

minlmreport class

#
# Optimization report, filled by MinLMResults() function
# 
# FIELDS:
# * TerminationType, completetion code:
#     * -8    optimizer detected NAN/INF values either in the function itself,
#             or in its Jacobian
#     * -7    derivative correctness check failed;
#             see rep.funcidx, rep.varidx for
#             more information.
#     * -5    inappropriate solver was used:
#             * solver created with minlmcreatefgh() used  on  problem  with
#               general linear constraints (set with minlmsetlc() call).
#     * -3    constraints are inconsistent
#     *  2    relative step is no more than EpsX.
#     *  5    MaxIts steps was taken
#     *  7    stopping conditions are too stringent,
#             further improvement is impossible
#     *  8    terminated   by  user  who  called  MinLMRequestTermination().
#             X contains point which was "current accepted" when termination
#             request was submitted.
# * IterationsCount, contains iterations count
# * NFunc, number of function calculations
# * NJac, number of Jacobi matrix calculations
# * NGrad, number of gradient calculations
# * NHess, number of Hessian calculations
# * NCholesky, number of Cholesky decomposition calculations
#

class minlmreport(object):
    ...

minlmstate class

#
# Levenberg-Marquardt optimizer.
# 
# This structure should be created using one of the MinLMCreate???()
# functions. You should not access its fields directly; use ALGLIB functions
# to work with it.
#

class minlmstate(object):
    ...

minlmcreatefgh function

#
#     LEVENBERG-MARQUARDT-LIKE METHOD FOR NON-LINEAR OPTIMIZATION
# 
# DESCRIPTION:
# This  function  is  used  to  find  minimum  of general form (not "sum-of-
# -squares") function
#     F = F(x[0], ..., x[n-1])
# using  its  gradient  and  Hessian.  Levenberg-Marquardt modification with
# L-BFGS pre-optimization and internal pre-conditioned  L-BFGS  optimization
# after each Levenberg-Marquardt step is used.
# 
# 
# REQUIREMENTS:
# This algorithm will request following information during its operation:
# 
# * function value F at given point X
# * F and gradient G (simultaneously) at given point X
# * F, G and Hessian H (simultaneously) at given point X
# 
# There are several overloaded versions of  MinLMOptimize()  function  which
# correspond  to  different LM-like optimization algorithms provided by this
# unit. You should choose version which accepts func(),  grad()  and  hess()
# function pointers. First pointer is used to calculate F  at  given  point,
# second  one  calculates  F(x)  and  grad F(x),  third one calculates F(x),
# grad F(x), hess F(x).
# 
# You can try to initialize MinLMState structure with FGH-function and  then
# use incorrect version of MinLMOptimize() (for example, version which  does
# not provide Hessian matrix), but it will lead to  exception  being  thrown
# after first attempt to calculate Hessian.
# 
# 
# USAGE:
# 1. User initializes algorithm state with MinLMCreateFGH() call
# 2. User tunes solver parameters with MinLMSetCond(),  MinLMSetStpMax() and
#    other functions
# 3. User calls MinLMOptimize() function which  takes algorithm  state   and
#    pointers (delegates, etc.) to callback functions.
# 4. User calls MinLMResults() to get solution
# 5. Optionally, user may call MinLMRestartFrom() to solve  another  problem
#    with same N but another starting point and/or another function.
#    MinLMRestartFrom() allows to reuse already initialized structure.
# 
# 
# INPUT PARAMETERS:
#     N       -   dimension, N>1
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     X       -   initial solution, array[0..N-1]
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTES:
# 1. you may tune stopping conditions with MinLMSetCond() function
# 2. if target function contains exp() or other fast growing functions,  and
#    optimization algorithm makes too large steps which leads  to  overflow,
#    use MinLMSetStpMax() function to bound algorithm's steps.
# 
#   -- ALGLIB --
#      Copyright 30.03.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlmcreatefgh(n, x)
SYNTAX: state = xalglib.minlmcreatefgh(x)

Examples:   [1]  

minlmcreatefgj function

#
# This is obsolete function.
# 
# Since ALGLIB 3.3 it is equivalent to MinLMCreateFJ().
# 
#   -- ALGLIB --
#      Copyright 30.03.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlmcreatefgj(n, m, x)
SYNTAX: state = xalglib.minlmcreatefgj(m, x)

minlmcreatefj function

#
# This function is considered obsolete since ALGLIB 3.1.0 and is present for
# backward  compatibility  only.  We  recommend  to use MinLMCreateVJ, which
# provides similar, but more consistent and feature-rich interface.
# 
#   -- ALGLIB --
#      Copyright 30.03.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlmcreatefj(n, m, x)
SYNTAX: state = xalglib.minlmcreatefj(m, x)

minlmcreatev function

#
#                 IMPROVED LEVENBERG-MARQUARDT METHOD FOR
#                  NON-LINEAR LEAST SQUARES OPTIMIZATION
# 
# DESCRIPTION:
# This function is used to find minimum of function which is represented  as
# sum of squares:
#     F(x) = f[0]^2(x[0],...,x[n-1]) + ... + f[m-1]^2(x[0],...,x[n-1])
# using value of function vector f[] only. Finite differences  are  used  to
# calculate Jacobian.
# 
# 
# REQUIREMENTS:
# This algorithm will request following information during its operation:
# * function vector f[] at given point X
# 
# There are several overloaded versions of  MinLMOptimize()  function  which
# correspond  to  different LM-like optimization algorithms provided by this
# unit. You should choose version which accepts fvec() callback.
# 
# You can try to initialize MinLMState structure with VJ  function and  then
# use incorrect version  of  MinLMOptimize()  (for  example,  version  which
# works with general form function and does not accept function vector), but
# it will  lead  to  exception being thrown after first attempt to calculate
# Jacobian.
# 
# 
# USAGE:
# 1. User initializes algorithm state with MinLMCreateV() call
# 2. User tunes solver parameters with MinLMSetCond(),  MinLMSetStpMax() and
#    other functions
# 3. User calls MinLMOptimize() function which  takes algorithm  state   and
#    callback functions.
# 4. User calls MinLMResults() to get solution
# 5. Optionally, user may call MinLMRestartFrom() to solve  another  problem
#    with same N/M but another starting point and/or another function.
#    MinLMRestartFrom() allows to reuse already initialized structure.
# 
# 
# INPUT PARAMETERS:
#     N       -   dimension, N>1
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     M       -   number of functions f[i]
#     X       -   initial solution, array[0..N-1]
#     DiffStep-   differentiation step, >0
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# See also MinLMIteration, MinLMResults.
# 
# NOTES:
# 1. you may tune stopping conditions with MinLMSetCond() function
# 2. if target function contains exp() or other fast growing functions,  and
#    optimization algorithm makes too large steps which leads  to  overflow,
#    use MinLMSetStpMax() function to bound algorithm's steps.
# 
#   -- ALGLIB --
#      Copyright 30.03.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlmcreatev(n, m, x, diffstep)
SYNTAX: state = xalglib.minlmcreatev(m, x, diffstep)

Examples:   [1]  [2]  [3]  

minlmcreatevgj function

#
# This is obsolete function.
# 
# Since ALGLIB 3.3 it is equivalent to MinLMCreateVJ().
# 
#   -- ALGLIB --
#      Copyright 30.03.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlmcreatevgj(n, m, x)
SYNTAX: state = xalglib.minlmcreatevgj(m, x)

minlmcreatevj function

#
#                 IMPROVED LEVENBERG-MARQUARDT METHOD FOR
#                  NON-LINEAR LEAST SQUARES OPTIMIZATION
# 
# DESCRIPTION:
# This function is used to find minimum of function which is represented  as
# sum of squares:
#     F(x) = f[0]^2(x[0],...,x[n-1]) + ... + f[m-1]^2(x[0],...,x[n-1])
# using value of function vector f[] and Jacobian of f[].
# 
# 
# REQUIREMENTS:
# This algorithm will request following information during its operation:
# 
# * function vector f[] at given point X
# * function vector f[] and Jacobian of f[] (simultaneously) at given point
# 
# There are several overloaded versions of  MinLMOptimize()  function  which
# correspond  to  different LM-like optimization algorithms provided by this
# unit. You should choose version which accepts fvec()  and jac() callbacks.
# First  one  is used to calculate f[] at given point, second one calculates
# f[] and Jacobian df[i]/dx[j].
# 
# You can try to initialize MinLMState structure with VJ  function and  then
# use incorrect version  of  MinLMOptimize()  (for  example,  version  which
# works  with  general  form function and does not provide Jacobian), but it
# will  lead  to  exception  being  thrown  after first attempt to calculate
# Jacobian.
# 
# 
# USAGE:
# 1. User initializes algorithm state with MinLMCreateVJ() call
# 2. User tunes solver parameters with MinLMSetCond(),  MinLMSetStpMax() and
#    other functions
# 3. User calls MinLMOptimize() function which  takes algorithm  state   and
#    callback functions.
# 4. User calls MinLMResults() to get solution
# 5. Optionally, user may call MinLMRestartFrom() to solve  another  problem
#    with same N/M but another starting point and/or another function.
#    MinLMRestartFrom() allows to reuse already initialized structure.
# 
# 
# INPUT PARAMETERS:
#     N       -   dimension, N>1
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size of X
#     M       -   number of functions f[i]
#     X       -   initial solution, array[0..N-1]
# 
# OUTPUT PARAMETERS:
#     State   -   structure which stores algorithm state
# 
# NOTES:
# 1. you may tune stopping conditions with MinLMSetCond() function
# 2. if target function contains exp() or other fast growing functions,  and
#    optimization algorithm makes too large steps which leads  to  overflow,
#    use MinLMSetStpMax() function to bound algorithm's steps.
# 
#   -- ALGLIB --
#      Copyright 30.03.2009 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minlmcreatevj(n, m, x)
SYNTAX: state = xalglib.minlmcreatevj(m, x)

Examples:   [1]  

minlmoptimize function

#
# This family of functions is used to launcn iterations of nonlinear optimizer
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     func    -   callback which calculates function (or merit function)
#                 value func at given point x
#     grad    -   callback which calculates function (or merit function)
#                 value func and gradient grad at given point x
#     hess    -   callback which calculates function (or merit function)
#                 value func, gradient grad and Hessian hess at given point x
#     fvec    -   callback which calculates function vector fi[]
#                 at given point x
#     jac     -   callback which calculates function vector fi[]
#                 and Jacobian jac at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# NOTES:
# 
# 1. Depending on function used to create state  structure,  this  algorithm
#    may accept Jacobian and/or Hessian and/or gradient.  According  to  the
#    said above, there ase several versions of this function,  which  accept
#    different sets of callbacks.
# 
#    This flexibility opens way to subtle errors - you may create state with
#    MinLMCreateFGH() (optimization using Hessian), but call function  which
#    does not accept Hessian. So when algorithm will request Hessian,  there
#    will be no callback to call. In this case exception will be thrown.
# 
#    Be careful to avoid such errors because there is no way to find them at
#    compile time - you can see them at runtime only.
# 
#   -- ALGLIB --
#      Copyright 10.03.2009 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmoptimize_v(state, fvec, rep = None, param = None)
SYNTAX: xalglib.minlmoptimize_vj(state, fvec, jac, rep = None, param = None)
SYNTAX: xalglib.minlmoptimize_fgh(state, func, grad, hess, rep = None, param = None)
SYNTAX: xalglib.minlmoptimize_fj(state, func, jac, rep = None, param = None)
SYNTAX: xalglib.minlmoptimize_fgj(state, func, grad, jac, rep = None, param = None)

Examples:   [1]  [2]  [3]  [4]  [5]  

minlmrequesttermination function

#
# This subroutine submits request for termination of running  optimizer.  It
# should be called from user-supplied callback when user decides that it  is
# time to "smoothly" terminate optimization process.  As  result,  optimizer
# stops at point which was "current accepted" when termination  request  was
# submitted and returns error code 8 (successful termination).
# 
# INPUT PARAMETERS:
#     State   -   optimizer structure
# 
# NOTE: after  request  for  termination  optimizer  may   perform   several
#       additional calls to user-supplied callbacks. It does  NOT  guarantee
#       to stop immediately - it just guarantees that these additional calls
#       will be discarded later.
# 
# NOTE: calling this function on optimizer which is NOT running will have no
#       effect.
# 
# NOTE: multiple calls to this function are possible. First call is counted,
#       subsequent calls are silently ignored.
# 
#   -- ALGLIB --
#      Copyright 08.10.2014 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmrequesttermination(state)

minlmrestartfrom function

#
# This  subroutine  restarts  LM  algorithm from new point. All optimization
# parameters are left unchanged.
# 
# This  function  allows  to  solve multiple  optimization  problems  (which
# must have same number of dimensions) without object reallocation penalty.
# 
# INPUT PARAMETERS:
#     State   -   structure used for reverse communication previously
#                 allocated with MinLMCreateXXX call.
#     X       -   new starting point.
# 
#   -- ALGLIB --
#      Copyright 30.07.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmrestartfrom(state, x)

Examples:   [1]  

minlmresults function

#
# Levenberg-Marquardt algorithm results
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[0..N-1], solution
#     Rep     -   optimization  report;  includes  termination   codes   and
#                 additional information. Termination codes are listed below,
#                 see comments for this structure for more info.
#                 Termination code is stored in rep.terminationtype field:
#                 * -8    optimizer detected NAN/INF values either in the
#                         function itself, or in its Jacobian
#                 * -7    derivative correctness check failed;
#                         see rep.funcidx, rep.varidx for
#                         more information.
#                 * -3    constraints are inconsistent
#                 *  2    relative step is no more than EpsX.
#                 *  5    MaxIts steps was taken
#                 *  7    stopping conditions are too stringent,
#                         further improvement is impossible
#                 *  8    terminated by user who called minlmrequesttermination().
#                         X contains point which was "current accepted" when
#                         termination request was submitted.
# 
#   -- ALGLIB --
#      Copyright 10.03.2009 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minlmresults(state)

Examples:   [1]  [2]  [3]  [4]  [5]  

minlmresultsbuf function

#
# Levenberg-Marquardt algorithm results
# 
# Buffered implementation of MinLMResults(), which uses pre-allocated buffer
# to store X[]. If buffer size is  too  small,  it  resizes  buffer.  It  is
# intended to be used in the inner cycles of performance critical algorithms
# where array reallocation penalty is too large to be ignored.
# 
#   -- ALGLIB --
#      Copyright 10.03.2009 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minlmresultsbuf(state, x, rep)

minlmsetacctype function

#
# This function is used to change acceleration settings
# 
# You can choose between three acceleration strategies:
# * AccType=0, no acceleration.
# * AccType=1, secant updates are used to update quadratic model after  each
#   iteration. After fixed number of iterations (or after  model  breakdown)
#   we  recalculate  quadratic  model  using  analytic  Jacobian  or  finite
#   differences. Number of secant-based iterations depends  on  optimization
#   settings: about 3 iterations - when we have analytic Jacobian, up to 2*N
#   iterations - when we use finite differences to calculate Jacobian.
# 
# AccType=1 is recommended when Jacobian  calculation  cost is prohibitively
# high (several Mx1 function vector calculations  followed  by  several  NxN
# Cholesky factorizations are faster than calculation of one M*N  Jacobian).
# It should also be used when we have no Jacobian, because finite difference
# approximation takes too much time to compute.
# 
# Table below list  optimization  protocols  (XYZ  protocol  corresponds  to
# MinLMCreateXYZ) and acceleration types they support (and use by  default).
# 
# ACCELERATION TYPES SUPPORTED BY OPTIMIZATION PROTOCOLS:
# 
# protocol    0   1   comment
# V           +   +
# VJ          +   +
# FGH         +
# 
# DEFAULT VALUES:
# 
# protocol    0   1   comment
# V               x   without acceleration it is so slooooooooow
# VJ          x
# FGH         x
# 
# NOTE: this  function should be called before optimization. Attempt to call
# it during algorithm iterations may result in unexpected behavior.
# 
# NOTE: attempt to call this function with unsupported protocol/acceleration
# combination will result in exception being thrown.
# 
#   -- ALGLIB --
#      Copyright 14.10.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetacctype(state, acctype)

minlmsetbc function

#
# This function sets boundary constraints for LM optimizer
# 
# Boundary constraints are inactive by default (after initial creation).
# They are preserved until explicitly turned off with another SetBC() call.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     BndL    -   lower bounds, array[N].
#                 If some (all) variables are unbounded, you may specify
#                 very small number or -INF (latter is recommended because
#                 it will allow solver to use better algorithm).
#     BndU    -   upper bounds, array[N].
#                 If some (all) variables are unbounded, you may specify
#                 very large number or +INF (latter is recommended because
#                 it will allow solver to use better algorithm).
# 
# NOTE 1: it is possible to specify BndL[i]=BndU[i]. In this case I-th
# variable will be "frozen" at X[i]=BndL[i]=BndU[i].
# 
# NOTE 2: this solver has following useful properties:
# * bound constraints are always satisfied exactly
# * function is evaluated only INSIDE area specified by bound constraints
#   or at its boundary
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetbc(state, bndl, bndu)

minlmsetcond function

#
# This function sets stopping conditions for Levenberg-Marquardt optimization
# algorithm.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     EpsX    -   >=0
#                 The subroutine finishes its work if  on  k+1-th  iteration
#                 the condition |v|<=EpsX is fulfilled, where:
#                 * |.| means Euclidian norm
#                 * v - scaled step vector, v[i]=dx[i]/s[i]
#                 * dx - ste pvector, dx=X(k+1)-X(k)
#                 * s - scaling coefficients set by MinLMSetScale()
#                 Recommended values: 1E-9 ... 1E-12.
#     MaxIts  -   maximum number of iterations. If MaxIts=0, the  number  of
#                 iterations   is    unlimited.   Only   Levenberg-Marquardt
#                 iterations  are  counted  (L-BFGS/CG  iterations  are  NOT
#                 counted because their cost is very low compared to that of
#                 LM).
# 
# Passing  EpsX=0  and  MaxIts=0  (simultaneously)  will  lead  to automatic
# stopping criterion selection (small EpsX).
# 
# NOTE: it is not recommended to set large EpsX (say, 0.001). Because LM  is
#       a second-order method, it performs very precise steps anyway.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetcond(state, epsx, maxits)

Examples:   [1]  [2]  [3]  [4]  [5]  

minlmsetgradientcheck function

#
# This  subroutine  turns  on  verification  of  the  user-supplied analytic
# gradient:
# * user calls this subroutine before optimization begins
# * MinLMOptimize() is called
# * prior to actual optimization, for  each  function Fi and each  component
#   of parameters  being  optimized X[j] algorithm performs following steps:
#   * two trial steps are made to X[j]-TestStep*S[j] and X[j]+TestStep*S[j],
#     where X[j] is j-th parameter and S[j] is a scale of j-th parameter
#   * if needed, steps are bounded with respect to constraints on X[]
#   * Fi(X) is evaluated at these trial points
#   * we perform one more evaluation in the middle point of the interval
#   * we  build  cubic  model using function values and derivatives at trial
#     points and we compare its prediction with actual value in  the  middle
#     point
#   * in case difference between prediction and actual value is higher  than
#     some predetermined threshold, algorithm stops with completion code -7;
#     Rep.VarIdx is set to index of the parameter with incorrect derivative,
#     Rep.FuncIdx is set to index of the function.
# * after verification is over, algorithm proceeds to the actual optimization.
# 
# NOTE 1: verification  needs  N (parameters count) Jacobian evaluations. It
#         is  very  costly  and  you  should use it only for low dimensional
#         problems,  when  you  want  to  be  sure  that  you've   correctly
#         calculated  analytic  derivatives.  You should not  use  it in the
#         production code  (unless  you  want  to check derivatives provided
#         by some third party).
# 
# NOTE 2: you  should  carefully  choose  TestStep. Value which is too large
#         (so large that function behaviour is significantly non-cubic) will
#         lead to false alarms. You may use  different  step  for  different
#         parameters by means of setting scale with MinLMSetScale().
# 
# NOTE 3: this function may lead to false positives. In case it reports that
#         I-th  derivative was calculated incorrectly, you may decrease test
#         step  and  try  one  more  time  - maybe your function changes too
#         sharply  and  your  step  is  too  large for such rapidly chanding
#         function.
# 
# INPUT PARAMETERS:
#     State       -   structure used to store algorithm state
#     TestStep    -   verification step:
#                     * TestStep=0 turns verification off
#                     * TestStep>0 activates verification
# 
#   -- ALGLIB --
#      Copyright 15.06.2012 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetgradientcheck(state, teststep)

minlmsetlc function

#
# This function sets general linear constraints for LM optimizer
# 
# Linear constraints are inactive by default (after initial creation).  They
# are preserved until explicitly turned off with another minlmsetlc() call.
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     C       -   linear constraints, array[K,N+1].
#                 Each row of C represents one constraint, either equality
#                 or inequality (see below):
#                 * first N elements correspond to coefficients,
#                 * last element corresponds to the right part.
#                 All elements of C (including right part) must be finite.
#     CT      -   type of constraints, array[K]:
#                 * if CT[i]>0, then I-th constraint is C[i,*]*x >= C[i,n+1]
#                 * if CT[i]=0, then I-th constraint is C[i,*]*x  = C[i,n+1]
#                 * if CT[i]<0, then I-th constraint is C[i,*]*x <= C[i,n+1]
#     K       -   number of equality/inequality constraints, K>=0:
#                 * if given, only leading K elements of C/CT are used
#                 * if not given, automatically determined from sizes of C/CT
# 
# IMPORTANT: if you have linear constraints, it is strongly  recommended  to
#            set scale of variables with minlmsetscale(). QP solver which is
#            used to calculate linearly constrained steps heavily relies  on
#            good scaling of input problems.
# 
# IMPORTANT: solvers created with minlmcreatefgh()  do  not  support  linear
#            constraints.
# 
# NOTE: linear  (non-bound)  constraints are satisfied only approximately  -
#       there  always  exists some violation due  to  numerical  errors  and
#       algorithmic limitations.
# 
# NOTE: general linear constraints  add  significant  overhead  to  solution
#       process. Although solver performs roughly same amount of  iterations
#       (when compared  with  similar  box-only  constrained  problem), each
#       iteration   now    involves  solution  of  linearly  constrained  QP
#       subproblem, which requires ~3-5 times more Cholesky  decompositions.
#       Thus, if you can reformulate your problem in such way  this  it  has
#       only box constraints, it may be beneficial to do so.
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetlc(state, c, ct, k)
SYNTAX: xalglib.minlmsetlc(state, c, ct)

minlmsetscale function

#
# This function sets scaling coefficients for LM optimizer.
# 
# ALGLIB optimizers use scaling matrices to test stopping  conditions  (step
# size and gradient are scaled before comparison with tolerances).  Scale of
# the I-th variable is a translation invariant measure of:
# a) "how large" the variable is
# b) how large the step should be to make significant changes in the function
# 
# Generally, scale is NOT considered to be a form of preconditioner.  But LM
# optimizer is unique in that it uses scaling matrix both  in  the  stopping
# condition tests and as Marquardt damping factor.
# 
# Proper scaling is very important for the algorithm performance. It is less
# important for the quality of results, but still has some influence (it  is
# easier  to  converge  when  variables  are  properly  scaled, so premature
# stopping is possible when very badly scalled variables are  combined  with
# relaxed stopping conditions).
# 
# INPUT PARAMETERS:
#     State   -   structure stores algorithm state
#     S       -   array[N], non-zero scaling coefficients
#                 S[i] may be negative, sign doesn't matter.
# 
#   -- ALGLIB --
#      Copyright 14.01.2011 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetscale(state, s)

minlmsetstpmax function

#
# This function sets maximum step length
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     StpMax  -   maximum step length, >=0. Set StpMax to 0.0,  if you don't
#                 want to limit step length.
# 
# Use this subroutine when you optimize target function which contains exp()
# or  other  fast  growing  functions,  and optimization algorithm makes too
# large  steps  which  leads  to overflow. This function allows us to reject
# steps  that  are  too  large  (and  therefore  expose  us  to the possible
# overflow) without actually calculating function value at the x+stp*d.
# 
# NOTE: non-zero StpMax leads to moderate  performance  degradation  because
# intermediate  step  of  preconditioned L-BFGS optimization is incompatible
# with limits on step size.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetstpmax(state, stpmax)

minlmsetxrep function

#
# This function turns on/off reporting.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     NeedXRep-   whether iteration reports are needed or not
# 
# If NeedXRep is True, algorithm will call rep() callback function if  it is
# provided to MinLMOptimize(). Both Levenberg-Marquardt and internal  L-BFGS
# iterations are reported.
# 
#   -- ALGLIB --
#      Copyright 02.04.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minlmsetxrep(state, needxrep)

minlm_d_fgh example

import xalglib

def function1_func(x, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    #
    return 100*(x[0]+3)**4 + (x[1]-3)**4

def function1_grad(x, grad, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # and its derivatives df/d0 and df/dx1
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    return func

def function1_hess(x, grad, hess, param):
    #
    # this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4
    # its derivatives df/d0 and df/dx1
    # and its Hessian.
    #
    func = 100*(x[0]+3)**4 + (x[1]-3)**4
    grad[0] = 400*(x[0]+3)**3
    grad[1] = 4*(x[1]-3)**3
    hess[0][0] = 1200*(x[0]+3)**2
    hess[0][1] = 0
    hess[1][0] = 0
    hess[1][1] = 12*(x[1]-3)**2
    return func

#
# This example demonstrates minimization of F(x0,x1) = 100*(x0+3)^4+(x1-3)^4
# using "FGH" mode of the Levenberg-Marquardt optimizer.
#
# F is treated like a monolitic function without internal structure,
# i.e. we do NOT represent it as a sum of squares.
#
# Optimization algorithm uses:
# * function value F(x0,x1)
# * gradient G={dF/dxi}
# * Hessian H={d2F/(dxi*dxj)}
#
x = [0,0]
epsx = 0.0000000001
maxits = 0

state = xalglib.minlmcreatefgh(x)
xalglib.minlmsetcond(state, epsx, maxits)
xalglib.minlmoptimize_fgh(state, function1_func, function1_grad, function1_hess)
x, rep = xalglib.minlmresults(state)

print(x) # expected [-3,+3]

minlm_d_restarts example

import xalglib

def function1_fvec(x, fi, param):
    #
    # this callback calculates
    # f0(x0,x1) = 100*(x0+3)^4,
    # f1(x0,x1) = (x1-3)^4
    #
    fi[0] = 10*(x[0]+3)**2
    fi[1] = (x[1]-3)**2
    return

def function2_fvec(x, fi, param):
    #
    # this callback calculates
    # f0(x0,x1) = x0^2+1
    # f1(x0,x1) = x1-1
    #
    fi[0] = x[0]*x[0]+1
    fi[1] = x[1]-1
    return

#
# This example demonstrates minimization of F(x0,x1) = f0^2+f1^2, where 
#
#     f0(x0,x1) = 10*(x0+3)^2
#     f1(x0,x1) = (x1-3)^2
#
# using several starting points and efficient restarts.
#
epsx = 0.0000000001
maxits = 0

#
# create optimizer using minlmcreatev()
#
x = [10,10]
state = xalglib.minlmcreatev(2, x, 0.0001)
xalglib.minlmsetcond(state, epsx, maxits)
xalglib.minlmoptimize_v(state, function1_fvec)
x, rep = xalglib.minlmresults(state)
print(x) # expected [-3,+3]

#
# restart optimizer using minlmrestartfrom()
#
# we can use different starting point, different function,
# different stopping conditions, but problem size
# must remain unchanged.
#
x = [4,4]
xalglib.minlmrestartfrom(state, x)
xalglib.minlmoptimize_v(state, function2_fvec)
x, rep = xalglib.minlmresults(state)
print(x) # expected [0,1]

minlm_d_v example

import xalglib

def function1_fvec(x, fi, param):
    #
    # this callback calculates
    # f0(x0,x1) = 100*(x0+3)^4,
    # f1(x0,x1) = (x1-3)^4
    #
    fi[0] = 10*(x[0]+3)**2
    fi[1] = (x[1]-3)**2
    return

#
# This example demonstrates minimization of F(x0,x1) = f0^2+f1^2, where 
#
#     f0(x0,x1) = 10*(x0+3)^2
#     f1(x0,x1) = (x1-3)^2
#
# using "V" mode of the Levenberg-Marquardt optimizer.
#
# Optimization algorithm uses:
# * function vector f[] = {f1,f2}
#
# No other information (Jacobian, gradient, etc.) is needed.
#
x = [0,0]
epsx = 0.0000000001
maxits = 0

state = xalglib.minlmcreatev(2, x, 0.0001)
xalglib.minlmsetcond(state, epsx, maxits)
xalglib.minlmoptimize_v(state, function1_fvec)
x, rep = xalglib.minlmresults(state)

print(x) # expected [-3,+3]

minlm_d_vb example

import xalglib

def function1_fvec(x, fi, param):
    #
    # this callback calculates
    # f0(x0,x1) = 100*(x0+3)^4,
    # f1(x0,x1) = (x1-3)^4
    #
    fi[0] = 10*(x[0]+3)**2
    fi[1] = (x[1]-3)**2
    return

#
# This example demonstrates minimization of F(x0,x1) = f0^2+f1^2, where 
#
#     f0(x0,x1) = 10*(x0+3)^2
#     f1(x0,x1) = (x1-3)^2
#
# with boundary constraints
#
#     -1 <= x0 <= +1
#     -1 <= x1 <= +1
#
# using "V" mode of the Levenberg-Marquardt optimizer.
#
# Optimization algorithm uses:
# * function vector f[] = {f1,f2}
#
# No other information (Jacobian, gradient, etc.) is needed.
#
x = [0,0]
bndl = [-1,-1]
bndu = [+1,+1]
epsx = 0.0000000001
maxits = 0

state = xalglib.minlmcreatev(2, x, 0.0001)
xalglib.minlmsetbc(state, bndl, bndu)
xalglib.minlmsetcond(state, epsx, maxits)
xalglib.minlmoptimize_v(state, function1_fvec)
x, rep = xalglib.minlmresults(state)

print(x) # expected [-1,+1]

minlm_d_vj example

import xalglib

def function1_fvec(x, fi, param):
    #
    # this callback calculates
    # f0(x0,x1) = 100*(x0+3)^4,
    # f1(x0,x1) = (x1-3)^4
    #
    fi[0] = 10*(x[0]+3)**2
    fi[1] = (x[1]-3)**2
    return

def function1_jac(x, fi, jac, param):
    #
    # this callback calculates
    # f0(x0,x1) = 100*(x0+3)^4,
    # f1(x0,x1) = (x1-3)^4
    # and Jacobian matrix J = [dfi/dxj]
    #
    fi[0] = 10*(x[0]+3)**2
    fi[1] = (x[1]-3)**2
    jac[0][0] = 20*(x[0]+3)
    jac[0][1] = 0
    jac[1][0] = 0
    jac[1][1] = 2*(x[1]-3)
    return

#
# This example demonstrates minimization of F(x0,x1) = f0^2+f1^2, where 
#
#     f0(x0,x1) = 10*(x0+3)^2
#     f1(x0,x1) = (x1-3)^2
#
# using "VJ" mode of the Levenberg-Marquardt optimizer.
#
# Optimization algorithm uses:
# * function vector f[] = {f1,f2}
# * Jacobian matrix J = {dfi/dxj}.
#
x = [0,0]
epsx = 0.0000000001
maxits = 0

state = xalglib.minlmcreatevj(2, x)
xalglib.minlmsetcond(state, epsx, maxits)
xalglib.minlmoptimize_vj(state, function1_fvec, function1_jac)
x, rep = xalglib.minlmresults(state)

print(x) # expected [-3,+3]

minnlc module

minnlcreport class

#
# This structure stores optimization report:
# * IterationsCount           total number of inner iterations
# * NFEV                      number of gradient evaluations
# * TerminationType           termination type (see below)
# 
# TERMINATION CODES
# 
# TerminationType field contains completion code, which can be:
#   -8    internal integrity control detected  infinite  or  NAN  values  in
#         function/gradient. Abnormal termination signalled.
#   -7    gradient verification failed.
#         See MinNLCSetGradientCheck() for more information.
#    1    relative function improvement is no more than EpsF.
#    2    relative step is no more than EpsX.
#    4    gradient norm is no more than EpsG
#    5    MaxIts steps was taken
#    7    stopping conditions are too stringent,
#         further improvement is impossible,
#         X contains best point found so far.
# 
# Other fields of this structure are not documented and should not be used!
#

class minnlcreport(object):
    ...

minnlcstate class

#
# This object stores nonlinear optimizer state.
# You should use functions provided by MinNLC subpackage to work  with  this
# object
#

class minnlcstate(object):
    ...

minnlccreate function

#
#                   NONLINEARLY  CONSTRAINED  OPTIMIZATION
#             WITH PRECONDITIONED AUGMENTED LAGRANGIAN ALGORITHM
# 
# DESCRIPTION:
# The  subroutine  minimizes  function   F(x)  of N arguments subject to any
# combination of:
# * bound constraints
# * linear inequality constraints
# * linear equality constraints
# * nonlinear equality constraints Gi(x)=0
# * nonlinear inequality constraints Hi(x)<=0
# 
# REQUIREMENTS:
# * user must provide function value and gradient for F(), H(), G()
# * starting point X0 must be feasible or not too far away from the feasible
#   set
# * F(), G(), H() are twice continuously differentiable on the feasible  set
#   and its neighborhood
# * nonlinear constraints G() and H() must have non-zero gradient at  G(x)=0
#   and at H(x)=0. Say, constraint like x^2>=1 is supported, but x^2>=0   is
#   NOT supported.
# 
# USAGE:
# 
# Constrained optimization if far more complex than the  unconstrained  one.
# Nonlinearly constrained optimization is one of the most esoteric numerical
# procedures.
# 
# Here we give very brief outline  of  the  MinNLC  optimizer.  We  strongly
# recommend you to study examples in the ALGLIB Reference Manual and to read
# ALGLIB User Guide on optimization, which is available at
# http://www.alglib.net/optimization/
# 
# 1. User initializes algorithm state with MinNLCCreate() call  and  chooses
#    what NLC solver to use. There is some solver which is used by  default,
#    with default settings, but you should NOT rely on  default  choice.  It
#    may change in future releases of ALGLIB without notice, and no one  can
#    guarantee that new solver will be  able  to  solve  your  problem  with
#    default settings.
# 
#    From the other side, if you choose solver explicitly, you can be pretty
#    sure that it will work with new ALGLIB releases.
# 
#    In the current release following solvers can be used:
#    * AUL solver (activated with MinNLCSetAlgoAUL() function)
# 
# 2. User adds boundary and/or linear and/or nonlinear constraints by  means
#    of calling one of the following functions:
#    a) MinNLCSetBC() for boundary constraints
#    b) MinNLCSetLC() for linear constraints
#    c) MinNLCSetNLC() for nonlinear constraints
#    You may combine (a), (b) and (c) in one optimization problem.
# 
# 3. User sets scale of the variables with MinNLCSetScale() function. It  is
#    VERY important to set  scale  of  the  variables,  because  nonlinearly
#    constrained problems are hard to solve when variables are badly scaled.
# 
# 4. User sets  stopping  conditions  with  MinNLCSetCond(). If  NLC  solver
#    uses  inner/outer  iteration  layout,  this  function   sets   stopping
#    conditions for INNER iterations.
# 
# 5. User chooses one of the  preconditioning  methods.  Preconditioning  is
#    very  important  for  efficient  handling  of boundary/linear/nonlinear
#    constraints. Without preconditioning algorithm would require  thousands
#    of iterations even for simple problems.  Several preconditioners can be
#    used:
#    a) inexact LBFGS-based, with O(N*K) evaluation time
#    b) exact low rank one,  with O(N*K^2) evaluation time
#    c) exact robust one,    with O(N^3+K*N^2) evaluation time
#    where K is a total number of general linear and  nonlinear  constraints
#    (box ones are not counted).
#    Since version 3.11.0 ALGLIB uses exact robust preconditioner as default
#    option, but in some cases exact low rank one may be better option.
# 
# 6. Finally, user calls MinNLCOptimize()  function  which  takes  algorithm
#    state and pointer (delegate, etc.) to callback function which calculates
#    F/G/H.
# 
# 7. User calls MinNLCResults() to get solution
# 
# 8. Optionally user may call MinNLCRestartFrom() to solve  another  problem
#    with same N but another starting point. MinNLCRestartFrom()  allows  to
#    reuse already initialized structure.
# 
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size ofX
#     X       -   starting point, array[N]:
#                 * it is better to set X to a feasible point
#                 * but X can be infeasible, in which case algorithm will try
#                   to find feasible point first, using X as initial
#                   approximation.
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
#   -- ALGLIB --
#      Copyright 06.06.2014 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minnlccreate(n, x)
SYNTAX: state = xalglib.minnlccreate(x)

Examples:   [1]  [2]  [3]  

minnlccreatef function

#
# This subroutine is a finite  difference variant of MinNLCCreate(). It uses
# finite differences in order to differentiate target function.
# 
# Description below contains information which is specific to this  function
# only. We recommend to read comments on MinNLCCreate() in order to get more
# information about creation of NLC optimizer.
# 
# INPUT PARAMETERS:
#     N       -   problem dimension, N>0:
#                 * if given, only leading N elements of X are used
#                 * if not given, automatically determined from size ofX
#     X       -   starting point, array[N]:
#                 * it is better to set X to a feasible point
#                 * but X can be infeasible, in which case algorithm will try
#                   to find feasible point first, using X as initial
#                   approximation.
#     DiffStep-   differentiation step, >0
# 
# OUTPUT PARAMETERS:
#     State   -   structure stores algorithm state
# 
# NOTES:
# 1. algorithm uses 4-point central formula for differentiation.
# 2. differentiation step along I-th axis is equal to DiffStep*S[I] where
#    S[] is scaling vector which can be set by MinNLCSetScale() call.
# 3. we recommend you to use moderate values of  differentiation  step.  Too
#    large step will result in too large TRUNCATION  errors, while too small
#    step will result in too large NUMERICAL  errors.  1.0E-4  can  be  good
#    value to start from.
# 4. Numerical  differentiation  is   very   inefficient  -   one   gradient
#    calculation needs 4*N function evaluations. This function will work for
#    any N - either small (1...10), moderate (10...100) or  large  (100...).
#    However, performance penalty will be too severe for any N's except  for
#    small ones.
#    We should also say that code which relies on numerical  differentiation
#    is  less   robust   and  precise.  Imprecise  gradient  may  slow  down
#    convergence, especially on highly nonlinear problems.
#    Thus  we  recommend to use this function for fast prototyping on small-
#    dimensional problems only, and to implement analytical gradient as soon
#    as possible.
# 
#   -- ALGLIB --
#      Copyright 06.06.2014 by Bochkanov Sergey
#

SYNTAX: state = xalglib.minnlccreatef(n, x, diffstep)
SYNTAX: state = xalglib.minnlccreatef(x, diffstep)

minnlcoptimize function

#
# This family of functions is used to launcn iterations of nonlinear optimizer
# 
# These functions accept following parameters:
#     state   -   algorithm state
#     fvec    -   callback which calculates function vector fi[]
#                 at given point x
#     jac     -   callback which calculates function vector fi[]
#                 and Jacobian jac at given point x
#     rep     -   optional callback which is called after each iteration
#                 can be NULL
#     ptr     -   optional pointer which is passed to func/grad/hess/jac/rep
#                 can be NULL
# 
# 
# NOTES:
# 
# 1. This function has two different implementations: one which  uses  exact
#    (analytical) user-supplied Jacobian, and one which uses  only  function
#    vector and numerically  differentiates  function  in  order  to  obtain
#    gradient.
# 
#    Depending  on  the  specific  function  used to create optimizer object
#    you should choose appropriate variant of MinNLCOptimize() -  one  which
#    accepts function AND Jacobian or one which accepts ONLY function.
# 
#    Be careful to choose variant of MinNLCOptimize()  which  corresponds to
#    your optimization scheme! Table below lists different  combinations  of
#    callback (function/gradient) passed to MinNLCOptimize()   and  specific
#    function used to create optimizer.
# 
# 
#                      |         USER PASSED TO MinNLCOptimize()
#    CREATED WITH      |  function only   |  function and gradient
#    ------------------------------------------------------------
#    MinNLCCreateF()   |     works               FAILS
#    MinNLCCreate()    |     FAILS               works
# 
#    Here "FAILS" denotes inappropriate combinations  of  optimizer creation
#    function  and  MinNLCOptimize()  version.   Attemps   to    use    such
#    combination will lead to exception. Either  you  did  not pass gradient
#    when it WAS needed or you passed gradient when it was NOT needed.
# 
#   -- ALGLIB --
#      Copyright 06.06.2014 by Bochkanov Sergey
#

SYNTAX: xalglib.minnlcoptimize_v(state, fvec, rep = None, param = None)
SYNTAX: xalglib.minnlcoptimize_j(state, jac, rep = None, param = None)

Examples:   [1]  [2]  [3]  

minnlcrestartfrom function

#
# This subroutine restarts algorithm from new point.
# All optimization parameters (including constraints) are left unchanged.
# 
# This  function  allows  to  solve multiple  optimization  problems  (which
# must have  same number of dimensions) without object reallocation penalty.
# 
# INPUT PARAMETERS:
#     State   -   structure previously allocated with MinNLCCreate call.
#     X       -   new starting point.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: xalglib.minnlcrestartfrom(state, x)

minnlcresults function

#
# MinNLC results
# 
# INPUT PARAMETERS:
#     State   -   algorithm state
# 
# OUTPUT PARAMETERS:
#     X       -   array[0..N-1], solution
#     Rep     -   optimization report. You should check Rep.TerminationType
#                 in  order  to  distinguish  successful  termination  from
#                 unsuccessful one:
#                 * -8    internal integrity control  detected  infinite or
#                         NAN   values   in   function/gradient.   Abnormal
#                         termination signalled.
#                 * -7   gradient verification failed.
#                        See MinNLCSetGradientCheck() for more information.
#                 *  1   relative function improvement is no more than EpsF.
#                 *  2   scaled step is no more than EpsX.
#                 *  4   scaled gradient norm is no more than EpsG.
#                 *  5   MaxIts steps was taken
#                 More information about fields of this  structure  can  be
#                 found in the comments on MinNLCReport datatype.
# 
#   -- ALGLIB --
#      Copyright 06.06.2014 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minnlcresults(state)

Examples:   [1]  [2]  [3]  

minnlcresultsbuf function

#
# NLC results
# 
# Buffered implementation of MinNLCResults() which uses pre-allocated buffer
# to store X[]. If buffer size is  too  small,  it  resizes  buffer.  It  is
# intended to be used in the inner cycles of performance critical algorithms
# where array reallocation penalty is too large to be ignored.
# 
#   -- ALGLIB --
#      Copyright 28.11.2010 by Bochkanov Sergey
#

SYNTAX: x, rep = xalglib.minnlcresultsbuf(state, x, rep)

minnlcsetalgoaul function

#
# This  function  tells MinNLC unit to use  Augmented  Lagrangian  algorithm
# for nonlinearly constrained  optimization.  This  algorithm  is  a  slight
# modification of one described in "A Modified Barrier-Augmented  Lagrangian
# Method for  Constrained  Minimization  (1999)"  by  D.GOLDFARB,  R.POLYAK,
# K. SCHEINBERG, I.YUZEFOVICH.
# 
# Augmented Lagrangian algorithm works by converting problem  of  minimizing
# F(x) subject to equality/inequality constraints   to unconstrained problem
# of the form
# 
#     min[ f(x) +
#         + Rho*PENALTY_EQ(x)   + SHIFT_EQ(x,Nu1) +
#         + Rho*PENALTY_INEQ(x) + SHIFT_INEQ(x,Nu2) ]
# 
# where:
# * Rho is a fixed penalization coefficient
# * PENALTY_EQ(x) is a penalty term, which is used to APPROXIMATELY  enforce
#   equality constraints
# * SHIFT_EQ(x) is a special "shift"  term  which  is  used  to  "fine-tune"
#   equality constraints, greatly increasing precision
# * PENALTY_INEQ(x) is a penalty term which is used to approximately enforce
#   inequality constraints
# * SHIFT_INEQ(x) is a special "shift"  term  which  is  used to "fine-tune"
#   inequality constraints, greatly increasing precision
# * Nu1/Nu2 are vectors of Lagrange coefficients which are fine-tuned during
#   outer iterations of algorithm
# 
# This  version  of  AUL  algorithm  uses   preconditioner,  which   greatly
# accelerates convergence. Because this  algorithm  is  similar  to  penalty
# methods,  it  may  perform  steps  into  infeasible  area.  All  kinds  of
# constraints (boundary, linear and nonlinear ones) may   be   violated   in
# intermediate points - and in the solution.  However,  properly  configured
# AUL method is significantly better at handling  constraints  than  barrier
# and/or penalty methods.
# 
# The very basic outline of algorithm is given below:
# 1) first outer iteration is performed with "default"  values  of  Lagrange
#    multipliers Nu1/Nu2. Solution quality is low (candidate  point  can  be
#    too  far  away  from  true  solution; large violation of constraints is
#    possible) and is comparable with that of penalty methods.
# 2) subsequent outer iterations  refine  Lagrange  multipliers  and improve
#    quality of the solution.
# 
# INPUT PARAMETERS:
#     State   -   structure which stores algorithm state
#     Rho     -   penalty coefficient, Rho>0:
#                 * large enough  that  algorithm  converges  with   desired
#                   precision. Minimum value is 10*max(S'*diag(H)*S),  where
#                   S is a scale matrix (set by MinNLCSetScale) and H  is  a
#                   Hessian of the function being minimized. If you can  not
#                   easily estimate Hessian norm,  see  our  recommendations
#                   below.
#                 * not TOO large to prevent ill-conditioning
#                 * for unit-scale problems (variables and Hessian have unit
#                   magnitude), Rho=100 or Rho=1000 can be used.
#                 * it is important to note that Rho is internally multiplied
#                   by scaling matrix, i.e. optimum value of Rho depends  on
#                   scale of variables specified  by  MinNLCSetScale().
#     ItsCnt  -   number of outer iterations:
#                 * ItsCnt=0 means that small number of outer iterations  is
#                   automatically chosen (10 iterations in current version).
#                 * ItsCnt=1 means that AUL algorithm performs just as usual
#                   barrier method.
#                 * ItsCnt>1 means that  AUL  algorithm  performs  specified
#                   number of outer iterations
# 
# HOW TO CHOOSE PARAMETERS
# 
# Nonlinear optimization is a tricky area and Augmented Lagrangian algorithm
# is sometimes hard to tune. Good values of  Rho  and  ItsCnt  are  problem-
# specific.  In  order  to  help  you   we   prepared   following   set   of
# recommendations:
# 
# * for  unit-scale  problems  (variables  and Hessian have unit magnitude),
#   Rho=100 or Rho=1000 can be used.
# 
# * start from  some  small  value of Rho and solve problem  with  just  one
#   outer iteration (ItcCnt=1). In this case algorithm behaves like  penalty
#   method. Increase Rho in 2x or 10x steps until you  see  that  one  outer
#   iteration returns point which is "rough approximation to solution".
# 
#   It is very important to have Rho so  large  that  penalty  term  becomes
#   constraining i.e. modified function becomes highly convex in constrained
#   directions.
# 
#   From the other side, too large Rho may prevent you  from  converging  to
#   the solution. You can diagnose it by studying number of inner iterations
#   performed by algorithm: too few (5-10 on  1000-dimensional  problem)  or
#   too many (orders of magnitude more than  dimensionality)  usually  means
#   that Rho is too large.
# 
# * with just one outer iteration you  usually  have  low-quality  solution.
#   Some constraints can be violated with very  large  margin,  while  other
#   ones (which are NOT violated in the true solution) can push final  point
#   too far in the inner area of the feasible set.
# 
#   For example, if you have constraint x0>=0 and true solution  x0=1,  then
#   merely a presence of "x0>=0" will introduce a bias towards larger values
#   of x0. Say, algorithm may stop at x0=1.5 instead of 1.0.
# 
# * after you found good Rho, you may increase number of  outer  iterations.
#   ItsCnt=10 is a good value. Subsequent outer iteration will refine values
#   of  Lagrange  multipliers.  Constraints  which  were  violated  will  be
#   enforced, inactive constraints will be dropped (corresponding multipliers
#   will be decreased). Ideally, you  should  see  10-1000x  improvement  in
#   constraint handling (constraint violation is reduced).
# 
# * if  you  see  that  algorithm  converges  to  vicinity  of solution, but
#   additional outer iterations do not refine solution,  it  may  mean  that
#   algorithm is unstable - it wanders around true  solution,  but  can  not
#   approach it. Sometimes algorithm may be stabilized by increasing Rho one
#   more time, making it 5x or 10x larger.
# 
# SCALING OF CONSTRAINTS [IMPORTANT]
# 
# AUL optimizer scales   variables   according   to   scale   specified   by
# MinNLCSetScale() function, so it can handle  problems  with  badly  scaled
# variables (as long as we KNOW their scales).   However,  because  function
# being optimized is a mix  of  original  function and  constraint-dependent
# penalty  functions, it  is   important  to   rescale  both  variables  AND
# constraints.
# 
# Say,  if  you  minimize f(x)=x^2 subject to 1000000*x>=0,  then  you  have
# constraint whose scale is different from that of target  function (another
# example is 0.000001*x>=0). It is also possible to have constraints   whose
# scales  are   misaligned:   1000000*x0>=0, 0.000001*x1<=0.   Inappropriate
# scaling may ruin convergence because minimizing x^2 subject to x>=0 is NOT
# same as minimizing it subject to 1000000*x>=0.
# 
# Because we  know  coefficients  of  boundary/linear  constraints,  we  can
# automatically rescale and normalize them. However,  there  is  no  way  to
# automatically rescale nonlinear constraints Gi(x) and  Hi(x)  -  they  are
# black boxes.
# 
# It means that YOU are the one who is  responsible  for  correct scaling of
# nonlinear constraints  Gi(x)  and  Hi(x).  We  recommend  you  to  rescale
# nonlinear constraints in such way that I-th component of dG/dX (or  dH/dx)
# has magnitude approximately equal to 1/S[i] (where S  is  a  scale  set by
# MinNLCSetScale() function).
# 
# WHAT IF IT DOES NOT CONVERGE?
# 
# It is possible that AUL algorithm fails to converge to precise  values  of
# Lagrange multipliers. It stops somewhere around true solution, but candidate
# point is still too far from solution, and some constraints  are  violated.
# Such kind of failure is specific for Lagrangian algorithms -  technically,
# they stop at some point, but this point is not constrained solution.
# 
# There are exist several reasons why algorithm may fail to converge:
# a) too loose stopping criteria for inner iteration
# b) degenerate, redundant constraints
# c) target function has unconstrained extremum exactly at the  boundary  of
#    some constraint
# d) numerical noise in the target function
# 
# In all these cases algorithm is unstable - each outer iteration results in
# large and almost random step which improves handling of some  constraints,
# but violates other ones (ideally  outer iterations should form a  sequence
# of progressively decreasing steps towards solution).
# 
# First reason possible is  that  too  loose  stopping  criteria  for  inner
# iteration were specified. Augmented Lagrangian algorithm solves a sequence
# of intermediate problems, and requries each of them to be solved with high
# precision. Insufficient precision results in incorrect update of  Lagrange
# multipliers.
# 
# Another reason is that you may have specified degenerate constraints: say,
# some constraint was repeated twice. In most cases AUL algorithm gracefully
# handles such situations, but sometimes it may spend too much time figuring
# out subtle degeneracies in constraint matrix.
# 
# Third reason is tricky and hard to diagnose. Consider situation  when  you
# minimize  f=x^2  subject to constraint x>=0.  Unconstrained   extremum  is
# located  exactly  at  the  boundary  of  constrained  area.  In  this case
# algorithm will tend to oscillate between negative  and  positive  x.  Each
# time it stops at x<0 it "reinforces" constraint x>=0, and each time it  is
# bounced to x>0 it "relaxes" constraint (and is  attracted  to  x<0).
# 
# Such situation  sometimes  happens  in  problems  with  hidden  symetries.
# Algorithm  is  got  caught  in  a  loop with  Lagrange  multipliers  being
# continuously increased/decreased. Luckily, such loop forms after at  least
# three iterations, so this problem can be solved by  DECREASING  number  of
# outer iterations down to 1-2 and increasing  penalty  coefficient  Rho  as
# much as possible.
# 
# Final reason is numerical noise. AUL algorithm is robust against  moderate
# noise (more robust than, say, active set methods),  but  large  noise  may
# destabilize algorithm.
# 
#   -- ALGLIB --
#      Copyright 06.06.2014 by Bochkanov Sergey
#

SYNTAX: xalglib.minnlcsetalgoaul(state, rho, itscnt)

Examples:   [1]  [2]  [3]  

minnlcsetbc function