Alglib Man

http://www.alglib.net/translator/man/manual.cpp.
html
1 Introduction 1.1 ALGLIB license 1.2 Documentation license 1.3 Reference Manual and User Guide 1.4 Acknowledgements 2 Getting started with ALGLIB 2.1 ALGLIB structure 2.1.1 Packages 2.1.2 Subpackages 2.2 Compatibility 2.2.1 CPU 2.2.2 Compiler 2.2.3 Optimization settings 2.3 Compiling ALGLIB 2.3.1 Adding to your project 2.3.2 Configuring for your compiler 2.3.3 Improving performance (CPU-specific and OS-specific optimizations) 2.4 Using ALGLIB 2.4.1 Global definitions 2.4.2 Datatypes 2.4.3 Constants 2.4.4 Functions 2.4.5 Working with vectors and matrices 2.4.6 Using functions: 'expert' and 'friendly' interfaces 2.4.7 Handling errors 2.4.8 Working with Level 1 BLAS functions 2.5 Advanced topics 2.5.1 Testing ALGLIB 3 ALGLIB reference manual
1 Introduction
1.1 ALGLIB license
ALGLIB is a free software whic h uses dual lic ensing. You c an either use it under GPL lic ense (version 2 or at your option any later version) or buy c ommerc ial lic ense without c opyleft requirement. A c opy of the GNU General Public License is available at http://www.fsf.org/lic ensing/lic enses A c opy of the c ommerc ial lic ense c an be found at http://www.alglib.net /commercial.php
1.2 Documentation license

This reference manual is lic ensed under BSD-like doc umentation lic ense: Copyright 1994-2009 Sergey Boc hkanov, ALGLIB Projec t. All rights reserved. Redistribution and use of this doc ument (ALGLIB Referenc e Manual) with or without modific ation, are permitted provided that suc h redistributions will retain the above c opyright notic e, this c ondition and the following disc laimer as the first (or last) lines of this file. THIS DOCUMENTATION IS PROVIDED BY THE ALGLIB PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE ALGLIB PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1 of 430
10/25/2011 03:12 PM
http://www.alglib.net/translator/man/manual.cpp.html
1.3 Reference Manual and User Guide

ALGLIB Project provides two sourc es of information: ALGLIB Referenc e Manual (this doc ument) and ALGLIB User Guide. ALGLIB Referenc e Manual c ontains full desc ription of all public ly ac c essible ALGLIB units ac c ompanied with examples. Reference Manual is foc used on the sourc e c ode: it doc uments units, func tions, struc tures and so on. If you want to know what unit YYY can do or what subroutines unit ZZZ c ontains Referenc e Manual is a plac e to go. Free software needs free documentation - that's why ALGLIB Referenc e Manual is lic ensed under BSD-like doc umentation lic ense. Additionally to the Referenc e Manual we provide you User Guide. User Guide is foc used on more general questions: how fast ALGLIB is? how reliable it is? what are the strong and weak sides of the algorithms used? We aim to make ALGLIB User Guide an important sourc e of information both about ALGLIB and numeric al analysis algorithms in general. We want it to be a book about algorithms, not just software doc umentation. And we want it to be unique - that's why ALGLIB User Guide is distributed under less-permissive personal-use-only lic ense.
1.4 Acknowledgements
ALGLIB was not possible without c ontribution of the next open sourc e projec ts: LAPACK Cephes GNU MP MPFR
2 Getting started with ALGLIB

2.1 ALGLIB structure
2.1.1 Packages
ALGLIB is a C++ interfac e to the c omputational c ore written in C. Both C library and C++ wrapper are automatically generated by code generation tools developed within ALGLIB projec t. Pre-3.0 versions of ALGLIB inc luded more than 100 units, but it was diffic ult to work with suc h large number of files. Sinc e ALGLIB 3.0 all units are merged into 11 packages and two support units: alglibmisc.cpp - c ontains different algorithms whic h are hard to c lassify dataanalysis.cpp - c ontains data mining algorithms diffequations.cpp - c ontains differential equation solvers fasttransforms.cpp - c ontains FFT and other related algorithms integration.cpp - c ontains numeric al integration algorithms interpolation.cpp - c ontains interpolation algorithms linalg.cpp - c ontains linear algebra algorithms optimization.cpp - c ontains optimization algorithms solv ers.cpp - c ontains linear and nonlinear solvers specialfunctions.cpp - c ontains spec ial func tions statistics.cpp - statistic s alglibinternal.cpp - c ontains internal func tions whic h are used by other pac kages, but not exposed to the external world ap.cpp - contains public ly ac c essible vec tor/matrix c lasses, most important and general func tions and other "basic" functionality One package may rely on other ones, but we have tried to reduc e number of dependenc ies. Every pac kage relies on ap.cpp and many pac kages rely on alglibinternal.cpp. But many pac kages require only these two to work, and many other packages need signific antly less than 13 pac kages. For example, statistics.cpp requires two packages mentioned above and only one additional pac kage - specialfunctions.cpp.
2 of 430
10/25/2011 03:12 PM
2.1.2 Subpackages
There is one more c onc ept to learn - subpackages. Every pac kage was c reated from several sourc e files. For example (as of ALGLIB 3.0.0), linalg.cpp was c reated by merging together 14 .c pp files (C++ interfac e) and 14 .c files (computational c ore). These files provide different func tionality: one of them c alc ulates triangular fac torizations, another generates random matric es, and so on. We've merged sourc e c ode, but what to do with their doc umentation? Of course, we can merge their doc umentation (as we've merged units) in one big list of func tions and data structures, but such list will be hard to read. Instead, we have dec ided to merge source code, but leave documentation separate. If you look at the list of ALGLIB pac kages, you will see that eac h pac kage inc ludes several subpac kages. For example, linalg.cpp inc ludes trfac, svd, evd and other subpac kages. These subpac kages do no exist as separate files, namespaces or other entities. They are just subsets of one large unit whic h provide signific antly different functionality. They have separate doc umentation sec tions, but if you want to use svd subpac kage, you have to inc lude linalg.h, not svd.h.
2.2 Compatibility
2.2.1 CPU
ALGLIB is compatible with any CPU whic h: supports double prec ision arithmetic s complies with IEEE 754 floating point standard (espec ially in its handling of IEEE spec ial values) either big-endian or little-endian (but not mixed-endian) Most mainstream CPU's (in partic ular, x86, x86_64 and SPARC) satisfy these requirements.
As for Intel architecture, ALGLIB works with both FPU-based and SSE-based implementations of floating point math. 80-bit internal representation used by Intel FPU is not a problem for ALGLIB.
2.2.2 Compiler
ALGLIB is compatible with any C++ c ompiler whic h: supports 32-bit and 64-bit signed integer datatypes emits code whic h handles comparisons with IEEE spec ial values without raising exc eption. We don't require that x/0 will return INF. But at least we must be able to compare double prec ision value with infinity or NAN without raising exception. All modern compilers (in partic ular, reasonably new versions of MSVC, GCC and Sun Studio) satisfy these requirements. However, some very old c ompilers (ten years old version of Borland C++ Builder, for example) may emit c ode which does not correctly works with IEEE spec ial values. If you use one of these old c ompilers, we rec ommend you to run ALGLIB test suite to ensure that library works.
2.2.3 Optimization settings

ALGLIB is compatible with any kind of optimizing c ompiler as long as: v olatile modifier is c orrec tly handled (i.e. c ompiler does not optimize volatile reads/writes) optimized c ode c orrec tly handles IEEE spec ial values Generally, all kinds of optimization that were marked by c ompiler vendor as "safe" are possible. For example, ALGLIB can be compiled: under MSVC: with /O1, /O2, /Og, /Os, /Ox, /Ot, /Oy, /fp:prec ise, /fp:exc ept, /fp:stric t under GCC: with -O1, -O2, -O3, -Os From the other side, following "unsafe" optimizations will break ALGLIB:
3 of 430
10/25/2011 03:12 PM
under MSVC: /fp:fast under GCC: -Ofast, -ffast-math
2.3 Compiling ALGLIB

2.3.1 Adding to your project
Adding ALGLIB to your projec t is easy - just pic k pac kages you need and... add them to your projec t! Under most used compilers (GCC, MSVC, Sun Studio) it will work without any additional settings. In other c ases you will need to define several preprocessor definitions (this topic will be detailed below), but everything will still be simple. As you see, ALGLIB has no projec t files or makefiles. Why? There are several reasons: first, because many ALGLIB users don't need separate static library (whic h will be c reated by invoking makefile) they prefer to integrate sourc e c ode in their projec ts. We have provided sc ript-based build system before, but majority of our users prefer to build ALGLIB themselves. second, bec ause we want ALGLIB to be usable in any programming environment, whether it is Visual Studio, GNU build system or something else. The best solution is to write pac kage whic h doesn't depend on any particular programming environment. In any case, compiling ALGLIB is so simple that even without projec t file you c an do it in several minutes.
2.3.2 Configuring for your compiler

If you use modern versions of MSVC, GCC or Sun Studio, you don't need to c onfigure ALGLIB at all. But if you use outdated versions of these c ompilers (or something else), then you may need to tune definitions of several data types: alglib_impl::ae_int32_t - signed integer whic h is 32 bits wide alglib_impl::ae_int64_t - signed integer whic h is 64 bits wide alglib_impl::ae_int_t - signed integer whic h has same width as pointer ALGLIB tries to autodetec t your c ompiler and to define these types in c ompiler-spec ific manner: ae_int32_t is defined as int, bec ause this type is 32 bits wide in all modern c ompilers. ae_int64_t is defined as _int64 (MSVC) or as signed long long (GCC, Sun Studio). ae_int_t is defined as ptrdiff_t. In most cases, it is enough. But if anything goes wrong, you have several options: if your compiler provides stdint.h, you c an define AE_HAVE_STDINT c onditional symbol alternatively, you c an manually define AE_INT32_T and/or AE_INT64_T and/or AE_INT_T symbols. Just assign datatype name to them, and ALGLIB will automatic ally use your definition. You c an define only one or two types (those whic h are not defined automatic ally).
2.3.3 Improving performance (CPU-specific and OS-specific optimizations)

You can improve performanc e of ALGLIB in a several ways: by compiling with advanc ed optimization turned on by telling ALGLIB about CPU it will run on ALGLIB has two-layered struc ture: some set of basic performanc e-c ritic al primitives is implemented using optimized code, and the rest of the library is built on top of these primitives. By default, ALGLIB uses generic C c ode to implement these primitives (matrix multiplic ation, dec ompositions, etc .). This c ode works everywhere from Intel to SPARC. However, you can tell ALGLIB that it will work under partic ular arc hitec ture by defining appropriate mac ro at the global level: defining AE_CPU=AE_INTEL - to tell ALGLIB that it will work under Intel When AE_CPU mac ro is defined and equals to the AE_INTEL, it enables SSE2 support. ALGLIB will use cpuid instruction to determine SSE2 presenc e at run-time and - in c ase we have SSE2 - to use SSE2-c apable c ode. ALGLIB uses SSE2 intrinsics which are portable ac ross different c ompilers and effic ient enough for most prac tic al purposes. As of ALGLIB 3.4,
4 of 430
10/25/2011 03:12 PM
SSE2 support is available for MSVC, GCC and Sun Studio users only.
2.4 Using ALGLIB

2.4.1 Global definitions
ALGLIB defines several c onditional symbols (all start with "AE_" whic h means "ALGLIB environment") and two namespaces: alglib_impl (c ontains c omputational c ore) and alglib (c ontains C++ interfac e). Although this manual mentions both alglib_impl and alglib namespac es, only alglib namespac e should be used by you. It contains user-friendly C++ interfac e with automatic memory management, exc eption handling and all other nice features. alglib_impl is less user-friendly, is less doc umented, and it is too easy to c rash your system or c ause memory leak if you use it direc tly.
2.4.2 Datatypes
ALGLIB (ap.h header) defines several "basic " datatypes (types whic h are used by all pac kages) and many packagespecific datatypes. "Basic " datatypes are: alglib::ae_int_t - signed integer type used by library alglib::complex - double prec ision c omplex datatype, safer replac ement for std::complex alglib::ap_error - exc eption whic h is thrown by library boolean_1d_array - 1-dimensional boolean array integer_1d_array - 1-dimensional integer array real_1d_array - 1-dimensional real (double prec ision) array complex_1d_array - 1-dimensional c omplex array boolean_2d_array - 2-dimensional boolean array integer_2d_array - 2-dimensional integer array real_2d_array - 2-dimensional real (double prec ision) array complex_2d_array - 2-dimensional c omplex array Package-specific datatypes are c lasses whic h c an be divided into two distinc t groups: "struct-like" c lasses with public fields whic h you c an ac c ess direc tly. "object-like" c lasses whic h have no public fields. You should use ALGLIB func tions to work with them.
2.4.3 Constants
The most important c onstants (defined in the ap.h header) from ALGLIB namespac e are: alglib::machineepsilon - small number whic h is close to the double prec ision &eps;, but is slightly larger alglib::maxrealnumber - very large number whic h is close to the maximum real number, but is slightly smaller alglib::minrealnumber - very small number whic h is close to the minimum nonzero real number, but is slightly larger alglib::fp_nan - NAN (non-signalling under most platforms exc ept for PA-RISC, where it is signalling; but when PA-RISC CPU is in its default state, it is silently c onverted to the quiet NAN) alglib::fp_posinf - positive infinity alglib::fp_neginf - negative infinity
2.4.4 Functions
The most important "basic " func tions from ALGLIB namespac e (ap.h header) are: alglib::randomreal() - returns random real number from [0,1) alglib::randominteger(mx) - returns random integer number from [0,nx); mx must be less than RAND_MAX alglib::fp_eq(v1,v2) - makes IEEE-c ompliant c omparison of two double prec ision numbers. If numbers are represented with greater prec ision than spec ified by IEEE 754 (as with Intel 80-bit FPU), this func tions c onverts them to 64 bits before c omparing. alglib::fp_neq(v1,v2) - makes IEEE-c ompliant c omparison of two double prec ision numbers.
5 of 430
10/25/2011 03:12 PM
alglib::fp_less(v1,v2) - makes IEEE-c ompliant c omparison of two double prec ision numbers. alglib::fp_less_eq(v1,v2) - makes IEEE-c ompliant c omparison of two double prec ision numbers. alglib::fp_greater(v1,v2) - makes IEEE-c ompliant c omparison of two double prec ision numbers. alglib::fp_greater_eq(v1,v2) - makes IEEE-c ompliant c omparison of two double prec ision numbers. alglib::fp_isnan - c hec ks whether number is NAN alglib::fp_isposinf - c hec ks whether number is +INF alglib::fp_isneginf - c hec ks whether number is -INF alglib::fp_isinf - c hec ks whether number is +INF or -INF alglib::fp_isfinite - c hec ks whether number is finite value (possibly subnormalized)
2.4.5 Working with vectors and matrices

ALGLIB (ap.h header) supports matrixes and vec tors (one-dimensional and two-dimensional arrays) of variable size, with numeration starting from zero. Everything starts from array c reation. You should distinguish the c reation of array c lass instanc e and the memory allocation for the array. When c reating the c lass instanc e, you c an use c onstruc tor without any parameters, that c reates an empty array without any elements. An attempt to address them may c ause the program failure. You can use copy and assignment c onstruc tors that c opy one array into another. If, during the c opy operation, the source array has no memory alloc ated for the array elements, destination array will c ontain no elements either. If the source array has memory alloc ated for its elements, destination array will alloc ate the same amount of memory and c opy the elements there. That is, the c opy operation yields into two independent arrays with indentic al c ontents. You can also create array from formatted string like "[]", "[true,FALSE,tRUe]", "[[]]]" or "[[1,2],[3.2,4], [5.2]]" (note: '.' is used as dec imal point independently from loc ale settings). alglib::boolean_1d_array b1; b1 = "[true]"; alglib::real_2d_array r2("[[2,3],[3,4]]"); alglib::real_2d_array r2_1("[[]]"); alglib::real_2d_array r2_2(r2); r2_1 = r2; alglib::complex_1d_array c2; c2 = "[]"; c2 = "[0]"; c2 = "[1,2i]"; c2 = "[+1-2i,-1+5i]"; c2 = "[ 4i-2, 8i+2]"; c2 = "[+4i-2, +8i+2]"; c2 = "[-4i-2, -8i+2]"; After an empty array has been c reated, you c an alloc ate memory for its elements, using the setlength() method. The content of the created array elements is not defined. If the setlength method is c alled for the array with already allocated memory, then, after c hanging its parameters, the newly alloc ated elements also bec ome undefined and the old content is destroyed. alglib::boolean_1d_array b1; b1.setlength(2); alglib::integer_2d_array r2; r2.setlength(4,3); Another way to initialize array is to c all setcontent() method. This method ac c epts pointer to data whic h are copied into newly allocated array. Vec tors are stored in c ontiguous order, matric es are stored row by row. alglib::real_1d_array r1; double _r1[] = {2, 3}; r1.setcontent(2,_r1);
6 of 430
10/25/2011 03:12 PM
alglib::real_2d_array r2; double _r2[] = {11, 12, 13, 21, 22, 23}; r2.setcontent(2,3,_r2); To access the array elements, an overloaded operator() or operator[] c an used. That is, the c ode addressing the element of array a with indexes [i,j] c an look like a(i,j) or a[i][j]. alglib::integer_1d_array a("[1,2,3]"); alglib::integer_1d_array b("[3,9,27]"); a[0] = b(0); alglib::integer_2d_array c("[[1,2,3],[9,9,9]]"); alglib::integer_2d_array d("[[3,9,27],[8,8,8]]"); d[1][1] = c(0,0); You can access c ontents of 1-dimensional array by c alling getcontent() method whic h returns pointer to the array memory. For historic al reasons 2-dimensional arrays do not provide getcontent() method, but you c an use create reference to any element of array. 2-dimensional arrays store data in row-major order with aligned rows (i.e. generally distance between rows is not equal to number of c olumns). You c an get stride (distanc e between c onsequtive elements in different rows) with getstride() c all. alglib::integer_1d_array a("[1,2]"); alglib::real_2d_array b("[[0,1],[10,11]]"); alglib::ae_int_t *a_row = a.getcontent();
// all double double double
three pointers point to the same location *b_row0 = &b[0][0]; *b_row0_2 = &b(0,0); *b_row0_3 = b[0];
// advancing to the next row of 2-dimensional array double *b_row1 = b_row0 + b.getstride();
Finally, you can get array size with length(), rows() or cols() methods: alglib::integer_1d_array a("[1,2]"); alglib::real_2d_array b("[[0,1],[10,11]]"); printf("%ld\n", (long)a.length()); printf("%ld\n", (long)b.rows()); printf("%ld\n", (long)b.cols());
2.4.6 Using functions: 'expert' and 'friendly' interfaces

Most ALGLIB func tions provide two interfac es: 'expert' and 'friendly'. What is the differenc e between two? When you use 'friendly' interface, ALGLIB: tries to automatic ally determine size of input arguments throws an exc eption when arguments have inc onsistent size (for example, square matrix is expec ted, but non-square is passed; another example - two parameters must have same size, but have different size) if semantic s of input parameter assumes that it is symmetric /Hermitian matrix, c hec ks that lower triangle is equal to upper triangle (c onjugate of upper triangle) and throws an exc eption otherwise if semantic s of output parameter assumes that it is symmetric /Hermitian matrix, returns full matrix (both upper and lower triangles) When you use 'expert' interfac e, ALGLIB: requires caller to explic itly spec ify size of input arguments. If vec tor/matrix is larger than size being spec ified (say, N), only N leading elements are used
7 of 430
10/25/2011 03:12 PM
if semantic s of input parameter assumes that it is symmetric /Hermitian matrix, uses only upper or lower triangle of input matrix and requires c aller to specify what triangle to use if semantic s of output parameter assumes that it is symmetric /Hermitian matrix, returns only upper or lower triangle (when you look at spec ific func tion, it is c lear what triangle is returned) Here are several examples of 'friendly' and 'expert' interfac es: #include "interpolation.h" ... alglib::real_1d_array x("[0,1,2,3]"); alglib::real_1d_array y("[1,5,3,9]"); alglib::real_1d_array y2("[1,5,3,9,0]"); alglib::spline1dinterpolant s; alglib::spline1dbuildlinear(x, y, 4, s); alglib::spline1dbuildlinear(x, y, s);
// 'expert' interface is used // 'friendly' interface - input size is // automatically determined
alglib::spline1dbuildlinear(x, y2, 4, s); // y2.length() is 5, but it will work alglib::spline1dbuildlinear(x, y2, s); 'Friendly' interface - matrix semantic s: #include "linalg.h" ... alglib::real_2d_array a; alglib::matinvreport rep; alglib::ae_int_t info;
// it won't work because sizes of x and y2 // are inconsistent
// // '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 alglib::spdmatrixinverse(a, info, rep); // you may try to pass nonsymmetric matrix a = "[[2,1],[0,2]]"; // but exception will be thrown in such case alglib::spdmatrixinverse(a, info, rep);
Same function but with 'expert' interfac e: #include "linalg.h" ... alglib::real_2d_array a; alglib::matinvreport rep; alglib::ae_int_t info;
8 of 430
10/25/2011 03:12 PM
// // 'Expert' interface, spdmatrixinverse() // // only upper triangle is used; a[1][0] is initialized by NAN, // but it can be arbitrary number a = "[[2,1],[NAN,2]]"; // after this line A will contain [[0.66,-0.33],[NAN,0.66]] // only upper triangle is modified alglib::spdmatrixinverse(a, 2 /* N */, true /* upper triangle is used */, info, rep);
2.4.7 Handling errors

ALGLIB uses two error handling strategies: returning error c ode throwing exc eption What is actually done depends on func tion being used and error being reported: 1. if function returns some error c ode and has c orresponding value for this kind of error, ALLGIB returns error c ode 2. if function does not return error c ode (or returns error c ode, but there is no c ode for error being reported), ALGLIB throws alglib::ap_error exc eption. Exc eption objec t has msg parameter whic h c ontains short desc ription of error. To make things clear we c onsider several examples of error handling. Example 1. minc greate func tion c reates nonlinear CG optimizer. It ac c epts problem size N and initial point X. Several things can go wrong - you may pass array whic h is too short, filled by NAN's, or otherwise pass inc orrec t data. However, this function returns no error c ode - so it throws an exc eption in c ase something goes wrong. There is no other way to tell caller that something went wrong. Example 2. rmatrixinverse func tion c alc ulates inverse matrix. It returns error c ode, whic h is set to +1 when problem is solved and is set to -3 if singular matrix was passed to the func tion. However, there is no error c ode for matrix which is non-square or contains infinities. Well, we c ould have c reated c orresponding error c odes - but we didn't. So if you pass singular matrix to rmatrixinverse, you will get c ompletion c ode -3. But if you pass matrix whic h c ontains INF in one of its elements, alglib::ap_error will be thrown. First error handling strategy (error c odes) is used to report "frequent" errors, whic h c an oc c ur during normal execution of user program. Sec ond error handling strategy (exc eptions) is used to report "rare" errors whic h are result of serious flaws in your program (or ALGLIB) - infinities/NAN's in the inputs, inc onsistent inputs, etc .
2.4.8 Working with Level 1 BLAS functions

ALGLIB (ap.h header) inc ludes following Level 1 BLAS func tions: alglib::vdotproduct() family, whic h allows to c alc ulate dot produc t of two real or c omplex vec tors alglib::vmove() family, whic h allows to c opy real/c omplex vec tor to another loc ation with optimal multiplication by real/complex value alglib::vmoveneg() family, whic h allows to c opy real/c omplex vec tor to another loc ation with multiplication by -1 alglib::vadd() and alglib::vsub() families, whic h allows to add or subtrac t two real/c omplex vectors with optimal multiplic ation by real/c omplex value alglib::vmul() family, whic h implements in-plac e multiplic ation of real/c omplex vec tor by real/c omplex value Each Level 1 BLAS func tion ac c epts input stride and output stride, whic h are expec ted to be positive. Input and output vectors should not overlap. Func tions operating with c omplex vec tors ac c ept additional parameter conj_src, which specifies whether input vec tor is c onjugated or not.
9 of 430
10/25/2011 03:12 PM
For each real/complex func tion there exists "simple" c ompanion whic h ac c epts no stride or c onjugation modifier. "Simple" function assumes that input/output stride is +1, and no input c onjugation is required. alglib::real_1d_array alglib::real_2d_array alglib::complex_1d_array alglib::complex_2d_array alglib::vmove(&rvec[0], alglib::vmove(&cvec[0], alglib::vmove(&cvec[2], rvec("[0,1,2,3]"); rmat("[[1,2],[3,4]]"); cvec("[0+1i,1+2i,2-1i,3-2i]"); cmat("[[3i,1],[9,2i]]"); 1, &rmat[0][0], rmat.getstride(), 2); // now rvec is [1,3,2,3]
1, &cmat[0][0], rmat.getstride(), "No conj", 2); // now cvec is [3i, 9, 2-1i, 1, &cmat[0][0], 1, "Conj", 2); // now cvec is [3i, 9, -3i,
Here is full list of Level 1 BLAS func tions implemented in ALGLIB: double vdotproduct( const double *v0, ae_int_t stride0, const double *v1, ae_int_t stride1, ae_int_t n); double vdotproduct( const double *v1, const double *v2, ae_int_t N); alglib::complex vdotproduct( const alglib::complex *v0, ae_int_t stride0, const char *conj0, const alglib::complex *v1, ae_int_t stride1, const char *conj1, ae_int_t n); alglib::complex vdotproduct( const alglib::complex *v1, const alglib::complex *v2, ae_int_t N); void vmove( double *vdst, ae_int_t stride_dst, const double* vsrc, ae_int_t stride_src, ae_int_t n); void vmove( double *vdst, const double* vsrc, ae_int_t N); void vmove( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex* vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n); void vmove( alglib::complex *vdst, const alglib::complex* vsrc,
10 of 430
10/25/2011 03:12 PM
ae_int_t N); void vmoveneg( double *vdst, ae_int_t stride_dst, const double* vsrc, ae_int_t stride_src, ae_int_t n); void vmoveneg( double *vdst, const double *vsrc, ae_int_t N); void vmoveneg( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex* vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n); void vmoveneg( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N); void vmove( double *vdst, ae_int_t stride_dst, const double* vsrc, ae_int_t stride_src, ae_int_t n, double alpha); void vmove( double *vdst, const double *vsrc, ae_int_t N, double alpha); void vmove( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex* vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n, double alpha); void vmove( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N, double alpha); void vmove( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex* vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n, alglib::complex alpha);
11 of 430
10/25/2011 03:12 PM
void vmove( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N, alglib::complex alpha); void vadd( double *vdst, ae_int_t stride_dst, const double *vsrc, ae_int_t stride_src, ae_int_t n); void vadd( double *vdst, const double *vsrc, ae_int_t N); void vadd( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex *vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n); void vadd( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N); void vadd( double *vdst, ae_int_t stride_dst, const double *vsrc, ae_int_t stride_src, ae_int_t n, double alpha); void vadd( double *vdst, const double *vsrc, ae_int_t N, double alpha); void vadd( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex *vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n, double alpha); void vadd( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N, double alpha); void vadd( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex *vsrc,
12 of 430
10/25/2011 03:12 PM
ae_int_t stride_src, const char *conj_src, ae_int_t n, alglib::complex alpha); void vadd( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N, alglib::complex alpha); void vsub( double *vdst, ae_int_t stride_dst, const double *vsrc, ae_int_t stride_src, ae_int_t n); void vsub( double *vdst, const double *vsrc, ae_int_t N); void vsub( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex *vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n); void vsub( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N); void vsub( double *vdst, ae_int_t stride_dst, const double *vsrc, ae_int_t stride_src, ae_int_t n, double alpha); void vsub( double *vdst, const double *vsrc, ae_int_t N, double alpha); void vsub( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex *vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n, double alpha); void vsub( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N, double alpha);
13 of 430
10/25/2011 03:12 PM
void vsub( alglib::complex *vdst, ae_int_t stride_dst, const alglib::complex *vsrc, ae_int_t stride_src, const char *conj_src, ae_int_t n, alglib::complex alpha); void vsub( alglib::complex *vdst, const alglib::complex *vsrc, ae_int_t N, alglib::complex alpha); void vmul( double *vdst, ae_int_t stride_dst, ae_int_t n, double alpha); void vmul( double *vdst, ae_int_t N, double alpha); void vmul( alglib::complex *vdst, ae_int_t stride_dst, ae_int_t n, double alpha); void vmul( alglib::complex *vdst, ae_int_t N, double alpha); void vmul( alglib::complex *vdst, ae_int_t stride_dst, ae_int_t n, alglib::complex alpha); void vmul( alglib::complex *vdst, ae_int_t N, alglib::complex alpha);
2.5 Advanced topics

2.5.1 Testing ALGLIB
There are two test suites in ALGLIB: c omputational tests and interfac e tests. Computational tests are loc ated in /tests /test_c.cpp. They are foc used on numeric al properties of algorithms, stress testing and "deep" tests (large automatically generated problems). They require signific ant amount of time to finish (tens of minutes). Interface tests are loc ated in /tests/test_i.cpp. These tests are foc used on ability to c orrec tly pass data between computational core and c aller, ability to detec t simple problems in inputs, and on ability to at least c ompile ALGLIB with your compiler. They are very fast (about a minute to finish inc luding c ompilation time). Running test suite is easy - just 1. define AE_USE_ALLOC_COUNTER (preproc essor definition) at the projec t level; it will turn on some malloc/free-
14 of 430
10/25/2011 03:12 PM
related chec ks 2. compile one of these files (test_c.cpp or test_i.cpp) along with the rest of the library 3. launch exec utable you will get. It may take from several sec onds (interfac e tests) to several minutes (c omputational tests) to get final results If you want to be sure that ALGLIB will work with some sophistic ated optimization settings, set c orresponding flags during compile time. If your c ompiler/system are not in the list of supported ones, we rec ommend you to run both test suites. But if you are running out of time, run at least test_i.cpp.
3 ALGLIB reference manual

Packages and subpackages
package hqrnd High quality random numbers generator nearestneighbor Nearest neighbor search: approximate and exact
AlglibMisc DataAnalysis
bdss dforest kmeans lda linreg logit mcpd mlpbase mlpe mlptrain pca
package Basic dataset functions Decision forest classifier (regression model) K-means++ clustering Linear discriminant analysis Linear models Logit models Markov Chains for Population/proportional Data Basic neural network operations Neural network ensemble models Neural network training Principal component analysis package Ordinary differential equation solver package Fast real/complex convolution Fast real/complex cross-correlation Real/complex FFT Real Fast Hartley Transform
DiffEquations
odesolver
FastTransforms
conv corr fft fht

Integration
autogk gkq gq
package Adaptive 1-dimensional integration Gauss-Kronrod quadrature generator Gaussian quadrature generator package Inverse distance weighting: interpolation/fitting Linear and nonlinear least-squares solvers Polynomial interpolation/fitting Parametric spline interpolation
10/25/2011 03:12 PM
Interpolation
idwint lsfit polint pspline

15 of 430
ratint spline1d spline2d package ablas bdsvd evd inverseupdate matdet matgen matinv ortfac rcond schur spdgevd svd trfac
LinAlg Optimization
Rational interpolation/fitting 1D spline interpolation/fitting 2D spline interpolation
Level 2 and Level 3 BLAS operations Bidiagonal SVD Eigensolvers Sherman-Morrison update of the inverse matrix Determinant calculation Random matrix generation Matrix inverse Real/complex QR/LQ, bi(tri)diagonal, Hessenberg decompositions Condition number estimate Schur decomposition Generalized symmetric eigensolver Singular value decomposition LU and Cholesky decompositions
minbleic mincg mincomp minlbfgs minlm minqp

Solvers
package Bound constrained optimizer with additional linear equality/inequality constraints Conjugate gradient optimizer Backward compatibility functions Limited memory BFGS optimizer Improved Levenberg-Marquardt optimizer Quadratic programming with bound and linear equality/inequality constraints
package densesolver nleq

SpecialFunctions
Dense linear system solver Solvers for nonlinear equations package Airy functions Bessel functions Beta function Binomial distribution Chebyshev polynomials Chi-Square distribution Dawson integral Elliptic integrals Exponential integrals F-distribution Fresnel integrals Gamma function Hermite polynomials Incomplete beta function Incomplete gamma function Jacobian elliptic functions Laguerre polynomials Legendre polynomials
10/25/2011 03:12 PM
airyf bessel betaf binomialdistr chebyshev chisquaredistr dawson elliptic expintegrals fdistr fresnel gammafunc hermite ibetaf igammaf jacobianelliptic laguerre legendre
16 of 430
normaldistr poissondistr psif studenttdistr trigintegrals

Statistics
Normal distribution Poisson distribution Psi function Student's t-distribution Trigonometric integrals
package basestat Mean, variance, covariance, correlation, etc. correlationtests Hypothesis testing: correlation tests jarquebera Hypothesis testing: Jarque-Bera test mannwhitneyu Hypothesis testing: Mann-Whitney-U test stest Hypothesis testing: sign test studentttests Hypothesis testing: Student's t-test variancetests Hypothesis testing: F-test and one-sample variance test wsr Hypothesis testing: Wilcoxon signed rank test
ablas
subpackage
Functions
cmatrixcopy cmatrixgemm cmatrixlefttrsm cmatrixmv cmatrixrank1 cmatrixrighttrsm cmatrixsyrk cmatrixtranspose rmatrixcopy rmatrixgemm rmatrixlefttrsm rmatrixmv rmatrixrank1 rmatrixrighttrsm rmatrixsyrk rmatrixtranspose
Examples
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 IB submatrix offset (row index)
17 of 430
10/25/2011 03:12 PM
JB submatrix offset (column index) *************************************************************************/ void alglib::cmatrixcopy( ae_int_t m, ae_int_t n, complex_2d_array a, ae_int_t ia, ae_int_t ja, complex_2d_array& b, ae_int_t ib, ae_int_t 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. INPUT PARAMETERS N matrix size, N>0 M 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 IC submatrix offset JC submatrix offset -- ALGLIB routine -16.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixgemm( ae_int_t m, ae_int_t n, ae_int_t k, alglib::complex alpha, complex_2d_array a,
18 of 430
10/25/2011 03:12 PM
ae_int_t ia, ae_int_t ja, ae_int_t optypea, complex_2d_array b, ae_int_t ib, ae_int_t jb, ae_int_t optypeb, alglib::complex beta, complex_2d_array& c, ae_int_t ic, ae_int_t jc);
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. 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 C matrix, actial matrix is stored in C[I2:I2+M-1,J2:J2+N-1] I2 submatrix offset J2 submatrix offset -- ALGLIB routine -15.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixlefttrsm( ae_int_t m, ae_int_t n, complex_2d_array a, ae_int_t i1, ae_int_t j1, bool isupper, bool isunit, ae_int_t optype, complex_2d_array& x, ae_int_t i2, ae_int_t j2);
cmatrixmv
function
/************************************************************************* Matrix-vector product: y := op(A)*x
19 of 430
10/25/2011 03:12 PM
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 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 *************************************************************************/ void alglib::cmatrixmv( ae_int_t m, ae_int_t n, complex_2d_array a, ae_int_t ia, ae_int_t ja, ae_int_t opa, complex_1d_array x, ae_int_t ix, complex_1d_array& y, ae_int_t 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 *************************************************************************/ void alglib::cmatrixrank1( ae_int_t m, ae_int_t n, complex_2d_array& a, ae_int_t ia,
20 of 430
10/25/2011 03:12 PM
ae_int_t ja, complex_1d_array& u, ae_int_t iu, complex_1d_array& v, ae_int_t 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. 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 C matrix, actial matrix is stored in C[I2:I2+M-1,J2:J2+N-1] I2 submatrix offset J2 submatrix offset -- ALGLIB routine -15.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixrighttrsm( ae_int_t m, ae_int_t n, complex_2d_array a, ae_int_t i1, ae_int_t j1, bool isupper, bool isunit, ae_int_t optype, complex_2d_array& x, ae_int_t i2, ae_int_t j2);
cmatrixsyrk
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.
21 of 430
10/25/2011 03:12 PM
* 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. INPUT PARAMETERS N matrix size, N>=0 K matrix size, K>=0 Alpha coefficient A matrix IA submatrix offset JA submatrix offset OpTypeA multiplication type: * 0 - A*A^H is calculated * 2 - A^H*A is calculated Beta coefficient C matrix IC submatrix offset JC submatrix offset IsUpper whether C is upper triangular or lower triangular -- ALGLIB routine -16.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixsyrk( ae_int_t n, ae_int_t k, double alpha, complex_2d_array a, ae_int_t ia, ae_int_t ja, ae_int_t optypea, double beta, complex_2d_array& c, ae_int_t ic, ae_int_t jc, bool 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) A destination matrix IB submatrix offset (row index) JB submatrix offset (column index) *************************************************************************/ void alglib::cmatrixtranspose( ae_int_t m, ae_int_t n, complex_2d_array a, ae_int_t ia, ae_int_t ja, complex_2d_array& b, ae_int_t ib,
22 of 430
10/25/2011 03:12 PM
ae_int_t 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 IB submatrix offset (row index) JB submatrix offset (column index) *************************************************************************/ void alglib::rmatrixcopy( ae_int_t m, ae_int_t n, real_2d_array a, ae_int_t ia, ae_int_t ja, real_2d_array& b, ae_int_t ib, ae_int_t jb);
rmatrixgemm
function
/************************************************************************* Same as CMatrixGEMM, but for real numbers. OpType may be only 0 or 1. -- ALGLIB routine -16.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixgemm( ae_int_t m, ae_int_t n, ae_int_t k, double alpha, real_2d_array a, ae_int_t ia, ae_int_t ja, ae_int_t optypea, real_2d_array b, ae_int_t ib, ae_int_t jb, ae_int_t optypeb, double beta, real_2d_array& c, ae_int_t ic, ae_int_t jc);
rmatrixlefttrsm
function
/*************************************************************************
23 of 430
10/25/2011 03:12 PM
Same as CMatrixLeftTRSM, but for real matrices OpType may be only 0 or 1. -- ALGLIB routine -15.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixlefttrsm( ae_int_t m, ae_int_t n, real_2d_array a, ae_int_t i1, ae_int_t j1, bool isupper, bool isunit, ae_int_t optype, real_2d_array& x, ae_int_t i2, ae_int_t 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 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 *************************************************************************/ void alglib::rmatrixmv( ae_int_t m, ae_int_t n, real_2d_array a, ae_int_t ia, ae_int_t ja, ae_int_t opa, real_1d_array x, ae_int_t ix, real_1d_array& y, ae_int_t iy);
24 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::rmatrixrank1( ae_int_t m, ae_int_t n, real_2d_array& a, ae_int_t ia, ae_int_t ja, real_1d_array& u, ae_int_t iu, real_1d_array& v, ae_int_t iv);
rmatrixrighttrsm
function
/************************************************************************* Same as CMatrixRightTRSM, but for real matrices OpType may be only 0 or 1. -- ALGLIB routine -15.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixrighttrsm( ae_int_t m, ae_int_t n, real_2d_array a, ae_int_t i1, ae_int_t j1, bool isupper, bool isunit, ae_int_t optype, real_2d_array& x, ae_int_t i2, ae_int_t j2);
rmatrixsyrk
function
/************************************************************************* Same as CMatrixSYRK, but for real matrices OpType may be only 0 or 1.
25 of 430
10/25/2011 03:12 PM
-- ALGLIB routine -16.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixsyrk( ae_int_t n, ae_int_t k, double alpha, real_2d_array a, ae_int_t ia, ae_int_t ja, ae_int_t optypea, double beta, real_2d_array& c, ae_int_t ic, ae_int_t jc, bool isupper);
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) A destination matrix IB submatrix offset (row index) JB submatrix offset (column index) *************************************************************************/ void alglib::rmatrixtranspose( ae_int_t m, ae_int_t n, real_2d_array a, ae_int_t ia, ae_int_t ja, real_2d_array& b, ae_int_t ib, ae_int_t jb);
airyf
subpackage
Functions
airy
Examples
airy
function
/************************************************************************* Airy function
26 of 430
10/25/2011 03:12 PM
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 when function > 1, For large negative For large positive Arithmetic IEEE IEEE IEEE IEEE IEEE IEEE domain -10, 0 0, 10 -10, 0 0, 10 -10, 10 -10, 10
absolute when function <= 1, relative except * denotes relative error criterion. x, the absolute error increases as x^1.5. x, the relative error increases as x^1.5. function Ai Ai Ai' Ai' Bi Bi' # trials 10000 10000 10000 10000 30000 30000 peak 1.6e-15 2.3e-14* 4.6e-15 1.8e-14* 4.2e-15 4.9e-15 rms 2.7e-16 1.8e-15* 7.6e-16 1.5e-15* 5.3e-16 7.3e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ void alglib::airy( double x, double& ai, double& aip, double& bi, double& bip);
autogk
Classes
autogkreport autogkstate
subpackage
Functions
autogkintegrate autogkresults autogksingular autogksmooth autogksmoothw
Examples
autogk_d1 Integrating f=exp(x) by adaptive integrator
autogkreport
class
27 of 430
10/25/2011 03:12 PM
/************************************************************************* 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 { ae_int_t terminationtype; ae_int_t nfev; ae_int_t nintervals; };
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 { };
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 *************************************************************************/ void autogkintegrate(autogkstate &state, void (*func)(double x, double xminusa, double bminusx, double &y, void *ptr), void *ptr = NULL); Examples: [1]
autogkresults
function
/************************************************************************* Adaptive integration results Called after AutoGKIteration returned False.
28 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::autogkresults( autogkstate state, double& v, autogkreport& rep); 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)âlpha" 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 *************************************************************************/ void alglib::autogksingular( double a, double b, double alpha, double beta, autogkstate& state);
autogksmooth
function
29 of 430
10/25/2011 03:12 PM
/************************************************************************* 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 continuous non-smooth integrands, but with less performance. used with
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 *************************************************************************/ void alglib::autogksmooth(double a, double b, autogkstate& state); 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 *************************************************************************/ void alglib::autogksmoothw( double a, double b, double xwidth, autogkstate& state);
30 of 430
10/25/2011 03:12 PM
autogk_d1 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "integration.h"
using namespace alglib; void int_function_1_func(double x, double xminusa, double bminusx, double &y, void *ptr) { // this callback calculates f(x)=exp(x) y = exp(x); } int main(int argc, char **argv) { // // 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 // double a = 0; double b = 1; autogkstate s; double v; autogkreport rep; autogksmooth(a, b, s); alglib::autogkintegrate(s, int_function_1_func); autogkresults(s, v, rep); printf("%.2f\n", double(v)); // EXPECTED: 1.7182 return 0; }
basestat
Functions
subpackage
cov2 covm covm2 pearsoncorr2 pearsoncorrelation pearsoncorrm pearsoncorrm2 sampleadev samplemedian samplemoments samplepercentile spearmancorr2 spearmancorrm spearmancorrm2 spearmanrankcorrelation
31 of 430
10/25/2011 03:12 PM
Examples
basestat_d_base basestat_d_c2 basestat_d_cm basestat_d_cm2 Basic func tionality (moments, adev, median, perc entile) Correlation (c ovarianc e) between two random variables Correlation (c ovarianc e) between c omponents of random vec tor Correlation (c ovarianc e) between two random vec tors
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 *************************************************************************/ double alglib::cov2(real_1d_array x, real_1d_array y); double alglib::cov2(real_1d_array x, real_1d_array y, ae_int_t n); Examples: [1]
covm
function
/************************************************************************* Covariance matrix 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 *************************************************************************/ void alglib::covm(real_2d_array x, real_2d_array& c); void alglib::covm( real_2d_array x, ae_int_t n, ae_int_t m, real_2d_array& c);
32 of 430
10/25/2011 03:12 PM
Examples: [1]
covm2
function
/************************************************************************* Cross-covariance matrix 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 *************************************************************************/ void alglib::covm2(real_2d_array x, real_2d_array y, real_2d_array& c); void alglib::covm2( real_2d_array x, real_2d_array y, ae_int_t n, ae_int_t m1, ae_int_t m2, real_2d_array& c); 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 *************************************************************************/ double alglib::pearsoncorr2(real_1d_array x, real_1d_array y);
33 of 430
10/25/2011 03:12 PM
double alglib::pearsoncorr2(real_1d_array x, real_1d_array y, ae_int_t n); Examples: [1]
pearsoncorrelation
function
/************************************************************************* Obsolete function, we recommend to use PearsonCorr2(). -- ALGLIB -Copyright 09.04.2007 by Bochkanov Sergey *************************************************************************/ double alglib::pearsoncorrelation( real_1d_array x, real_1d_array y, ae_int_t n);
pearsoncorrm
function
/************************************************************************* Pearson product-moment correlation matrix 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 *************************************************************************/ void alglib::pearsoncorrm(real_2d_array x, real_2d_array& c); void alglib::pearsoncorrm( real_2d_array x, ae_int_t n, ae_int_t m, real_2d_array& c); Examples: [1]
pearsoncorrm2
function
/************************************************************************* Pearson product-moment cross-correlation matrix 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:
34 of 430
10/25/2011 03:12 PM
* J-th column corresponds to J-th variable * I-th row corresponds to I-th observation 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>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>0, number of variables in Y: * if given, only leading M1 columns of X are used * if not given, automatically determined from input size
N M1 M2
OUTPUT PARAMETERS: C array[M1,M2], cross-correlation matrix (zero if N=0 or N=1) -- ALGLIB -Copyright 28.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pearsoncorrm2( real_2d_array x, real_2d_array y, real_2d_array& c); void alglib::pearsoncorrm2( real_2d_array x, real_2d_array y, ae_int_t n, ae_int_t m1, ae_int_t m2, real_2d_array& c); Examples: [1]
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: ADevADev -- ALGLIB -Copyright 06.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::sampleadev(real_1d_array x, double& adev); void alglib::sampleadev(real_1d_array x, ae_int_t n, double& adev); Examples: [1]
samplemedian
function
/************************************************************************* Median calculation. Input parameters:
35 of 430
10/25/2011 03:12 PM
X N sample (array indexes: [0..N-1]) 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 *************************************************************************/ void alglib::samplemedian(real_1d_array x, double& median); void alglib::samplemedian(real_1d_array x, ae_int_t n, double& median); 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. Variancevariance. Skewnessskewness (if variance<>0; zero otherwise). Kurtosiskurtosis (if variance<>0; zero otherwise). -- ALGLIB -Copyright 06.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::samplemoments( real_1d_array x, double& mean, double& variance, double& skewness, double& kurtosis); void alglib::samplemoments( real_1d_array x, ae_int_t n, double& mean, double& variance, double& skewness, double& kurtosis); Examples: [1]
samplepercentile
function
/************************************************************************* Percentile calculation. Input parameters: X sample (array indexes: [0..N-1])
36 of 430
10/25/2011 03:12 PM
N P N>=0, sample size: * if given, only leading N elements of X are processed * if not given, automatically determined from size of X percentile (0<=P<=1)
Output parameters: V percentile -- ALGLIB -Copyright 01.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::samplepercentile(real_1d_array x, double p, double& v); void alglib::samplepercentile( real_1d_array x, ae_int_t n, double p, double& v); Examples: [1]
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 *************************************************************************/ double alglib::spearmancorr2(real_1d_array x, real_1d_array y); double alglib::spearmancorr2( real_1d_array x, real_1d_array y, ae_int_t n); Examples: [1]
spearmancorrm
function
/************************************************************************* Spearman's rank correlation matrix 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:
37 of 430
10/25/2011 03:12 PM
* 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 *************************************************************************/ void alglib::spearmancorrm(real_2d_array x, real_2d_array& c); void alglib::spearmancorrm( real_2d_array x, ae_int_t n, ae_int_t m, real_2d_array& c); Examples: [1]
spearmancorrm2
function
/************************************************************************* Spearman's rank cross-correlation matrix 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 *************************************************************************/ void alglib::spearmancorrm2( real_2d_array x, real_2d_array y, real_2d_array& c); void alglib::spearmancorrm2( real_2d_array x, real_2d_array y, ae_int_t n, ae_int_t m1, ae_int_t m2, real_2d_array& c); Examples: [1]
spearmanrankcorrelation
function
10/25/2011 03:12 PM
38 of 430
/************************************************************************* Obsolete function, we recommend to use SpearmanCorr2(). -- ALGLIB -Copyright 09.04.2007 by Bochkanov Sergey *************************************************************************/ double alglib::spearmanrankcorrelation( real_1d_array x, real_1d_array y, ae_int_t n);
basestat_d_base example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "statistics.h"
using namespace alglib; int main(int argc, char **argv) { real_1d_array x = "[0,1,4,9,16,25,36,49,64,81]"; double mean; double variance; double skewness; double kurtosis; double adev; double p; double v; // // Here we demonstrate calculation of sample moments // (mean, variance, skewness, kurtosis) // samplemoments(x, mean, variance, skewness, kurtosis); printf("%.1f\n", double(mean)); // EXPECTED: 28.5 printf("%.1f\n", double(variance)); // EXPECTED: 801.1667 printf("%.1f\n", double(skewness)); // EXPECTED: 0.5751 printf("%.1f\n", double(kurtosis)); // EXPECTED: -1.2666 // // Average deviation // sampleadev(x, adev); printf("%.1f\n", double(adev)); // EXPECTED: 23.2 // // Median and percentile // samplemedian(x, v); printf("%.1f\n", double(v)); // EXPECTED: 20.5 p = 0.5; samplepercentile(x, p, v); printf("%.1f\n", double(v)); // EXPECTED: 20.5 return 0; }
39 of 430
10/25/2011 03:12 PM
basestat_d_c2 example
using namespace alglib; int main(int argc, char **argv) { // // We have two samples - x and y, and want to measure dependency between them // real_1d_array x = "[0,1,4,9,16,25,36,49,64,81]"; real_1d_array y = "[0,1,2,3,4,5,6,7,8,9]"; double v; // // Three dependency measures are calculated: // * covariation // * Pearson correlation // * Spearman rank correlation // v = cov2(x, y); printf("%.2f\n", double(v)); // EXPECTED: 82.5 v = pearsoncorr2(x, y); printf("%.2f\n", double(v)); // EXPECTED: 0.9627 v = spearmancorr2(x, y); printf("%.2f\n", double(v)); // EXPECTED: 1.000 return 0; }
basestat_d_cm example
using namespace alglib; int main(int argc, char **argv) { // // X is a sample matrix: // * I-th row corresponds to I-th observation // * J-th column corresponds to J-th variable // real_2d_array x = "[[1,0,1],[1,1,0],[-1,1,0],[-2,-1,1],[-1,0,9]]"; real_2d_array c; // // Three dependency measures are calculated: // * covariation // * Pearson correlation
40 of 430
10/25/2011 03:12 PM
// * 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. // covm(x, c); printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [[1.80,0.60,-1.40],[0.60,0.70,-0.80],[-1.40,-0.80,14. pearsoncorrm(x, c); printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [[1.000,0.535,-0.272],[0.535,1.000,-0.249],[-0.272,-0 spearmancorrm(x, c); printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [[1.000,0.556,-0.306],[0.556,1.000,-0.750],[-0.306,-0 return 0; }
basestat_d_cm2 example
using namespace alglib; int main(int argc, char **argv) { // // X and Y are sample matrices: // * I-th row corresponds to I-th observation // * J-th column corresponds to J-th variable // real_2d_array x = "[[1,0,1],[1,1,0],[-1,1,0],[-2,-1,1],[-1,0,9]]"; real_2d_array y = "[[2,3],[2,1],[-1,6],[-9,9],[7,1]]"; real_2d_array c; // // 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. // covm2(x, y, c); printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [[4.100,-3.250],[2.450,-1.500],[13.450,-5.750]] pearsoncorrm2(x, y, c); printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [[0.519,-0.699],[0.497,-0.518],[0.596,-0.433]] spearmancorrm2(x, y, c); printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [[0.541,-0.649],[0.216,-0.433],[0.433,-0.135]] return 0; }
bdss
subpackage
41 of 430
10/25/2011 03:12 PM
Functions
dsoptimalsplit2 dsoptimalsplit2fast
Examples
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, PBLprobabilities P(0|v<Threshold) and P(1|v<Threshold) PAR, PBRprobabilities P(0|v>=Threshold) and P(1|v>=Threshold) CVE cross-validation estimate of cross-entropy -- ALGLIB -Copyright 22.05.2008 by Bochkanov Sergey *************************************************************************/ void alglib::dsoptimalsplit2( real_1d_array a, integer_1d_array c, ae_int_t n, ae_int_t& info, double& threshold, double& pal, double& pbl, double& par, double& pbr, double& cve);
dsoptimalsplit2fast
function
/************************************************************************* Optimal partition, internal subroutine. Fast version. Accepts: A C TiesBuf CntBuf Alpha array[0..N-1] array[0..N-1] array[0..N] array[0..2*NC-1] array of attributes array[0..N-1] array of class labels temporaries (ties) temporaries (counts) centering factor (0<=alpha<=1, recommended value - 0.05)
42 of 430
10/25/2011 03:12 PM
BufR BufI Output: Info RMS CVRMS array[0..N-1] array[0..N-1] temporaries temporaries
error code (">0"=OK, "<0"=bad) training set RMS error 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 *************************************************************************/ void alglib::dsoptimalsplit2fast( real_1d_array& a, integer_1d_array& c, integer_1d_array& tiesbuf, integer_1d_array& cntbuf, real_1d_array& bufr, integer_1d_array& bufi, ae_int_t n, ae_int_t nc, double alpha, ae_int_t& info, double& threshold, double& rms, double& cvrms);
bdsvd
subpackage
Functions
rmatrixbdsvd
Examples
rmatrixbdsvd
function
/************************************************************************* Singular value decomposition of a bidiagonal matrix (extended algorithm) 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
43 of 430
10/25/2011 03:12 PM
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 accuracy to search singular values with. 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). 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. *************************************************************************/ bool alglib::rmatrixbdsvd( real_1d_array& d, real_1d_array e, ae_int_t n, bool isupper,
44 of 430
10/25/2011 03:12 PM
bool isfractionalaccuracyrequired, real_2d_array& u, ae_int_t nru, real_2d_array& c, ae_int_t ncc, real_2d_array& vt, ae_int_t ncvt);
bessel
Functions
besseli0 besseli1 besselj0 besselj1 besseljn besselk0 besselk1 besselkn bessely0 bessely1 besselyn
subpackage
Examples
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: arithmetic IEEE domain 0,30 Relative error: # trials peak 30000 5.8e-16 rms 1.4e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::besseli0(double x);
besseli1
function
/************************************************************************* Modified Bessel function of order one
45 of 430
10/25/2011 03:12 PM
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: arithmetic IEEE domain 0, 30 Relative error: # trials peak 30000 1.9e-15 rms 2.1e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1985, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::besseli1(double 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: arithmetic IEEE domain 0, 30 Absolute error: # trials peak 60000 4.2e-16 rms 1.1e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::besselj0(double x);
besselj1
function
/************************************************************************* Bessel function of order one
46 of 430
10/25/2011 03:12 PM
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: arithmetic IEEE domain 0, 30 Absolute error: # trials peak 30000 2.6e-16 rms 1.1e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::besselj1(double 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: arithmetic IEEE range 0, 30 Absolute error: # trials peak 5000 4.4e-16 rms 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 *************************************************************************/ double alglib::besseljn(ae_int_t n, double 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
47 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ double alglib::besselk0(double 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: arithmetic IEEE domain 0, 30 Relative error: # trials peak 30000 1.2e-15 rms 1.6e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::besselk1(double 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: arithmetic IEEE domain 0,30 Relative error: # trials peak 90000 1.8e-8 rms 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
48 of 430
10/25/2011 03:12 PM
Copyright 1984, 1987, 1988, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::besselkn(ae_int_t nn, double 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 IEEE domain 0, 30 # trials 30000 peak 1.3e-15 rms 1.6e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::bessely0(double 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: arithmetic IEEE domain 0, 30 Absolute error: # trials peak 30000 1.0e-15 rms 1.3e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::bessely1(double x);
49 of 430
10/25/2011 03:12 PM
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: arithmetic IEEE domain 0, 30 Absolute error, except relative when y > 1: # trials peak rms 30000 3.4e-15 4.3e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::besselyn(ae_int_t n, double x);
betaf
subpackage
Functions
beta
Examples
beta
function
/************************************************************************* Beta function | (a) | (b) -----------. | (a+b)
beta( a, b )
For large arguments the logarithm of the function is evaluated using lgam(), then exponentiated. ACCURACY: arithmetic IEEE domain 0,30 Relative error: # trials peak 30000 8.1e-14 rms 1.1e-14
50 of 430
10/25/2011 03:12 PM
Cephes Math Library Release 2.0: April, 1987 Copyright 1984, 1987 by Stephen L. Moshier *************************************************************************/ double alglib::beta(double a, double b);
binomialdistr
Functions
binomialcdistribution binomialdistribution invbinomialdistribution
subpackage
Examples
binomialcdistribution
function
/************************************************************************* Complemented binomial distribution Returns the sum of the terms k+1 through n of the Binomial probability density: n -- ( n ) > ( ) -- ( j ) j=k+1 j p (1-p) n-j
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 arithmetic domain # trials For p between 0.001 and 1: IEEE 0,100 100000 For p between 0 and .001: IEEE 0,100 100000 Relative error: peak rms 6.7e-15 1.5e-13 8.2e-16 2.7e-15
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::binomialcdistribution(ae_int_t k, ae_int_t n, double p);
binomialdistribution
function
/************************************************************************* Binomial distribution
51 of 430
10/25/2011 03:12 PM
Returns the sum of the terms 0 through k of the Binomial probability density: k -> -j=0 ( n ) ( ) ( j ) j p (1-p) n-j
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 arithmetic domain # trials For p between 0.001 and 1: IEEE 0,100 100000 Relative error: peak rms 4.3e-15 2.6e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::binomialdistribution(ae_int_t k, ae_int_t n, double 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 arithmetic domain # trials For p between 0.001 and 1: IEEE 0,100 100000 IEEE 0,10000 100000 For p between 10^-6 and 0.001: IEEE 0,100 100000 IEEE 0,10000 100000 Relative error: peak rms 2.3e-14 6.6e-12 2.0e-12 1.5e-12 6.4e-16 1.2e-13 1.3e-14 3.2e-14
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::invbinomialdistribution(ae_int_t k, ae_int_t n, double y);
52 of 430
10/25/2011 03:12 PM
chebyshev
Functions
subpackage
chebyshevcalculate chebyshevcoeffic ients chebyshevsum fromchebyshev
Examples
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 *************************************************************************/ double alglib::chebyshevcalculate(ae_int_t r, ae_int_t n, double 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 *************************************************************************/ void alglib::chebyshevcoefficients(ae_int_t n, real_1d_array& c);
chebyshevsum
function
/************************************************************************* Summation of Chebyshev polynomials using Clenshaws 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.
53 of 430
10/25/2011 03:12 PM
n x degree, n>=0 argument
Result: the value of the Chebyshev polynomial at x *************************************************************************/ double alglib::chebyshevsum( real_1d_array c, ae_int_t r, ae_int_t n, double 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 *************************************************************************/ void alglib::fromchebyshev(real_1d_array a, ae_int_t n, real_1d_array& b);
chisquaredistr
Functions
chisquarecdistribution chisquaredistribution invchisquaredistribution
subpackage
Examples
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. | | v/2-1 -t/2 | t e dt | | x
P( x | v )
1 ----------v/2 2 | (v/2)
54 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ double alglib::chisquarecdistribution(double v, double 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 P( x | v ) = 1 ----------v/2 2 | (v/2) | | v/2-1 -t/2 | t e dt | | 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 *************************************************************************/ double alglib::chisquaredistribution(double v, double x);
invchisquaredistribution
function
/************************************************************************* Inverse of complemented Chi-square distribution
55 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ double alglib::invchisquaredistribution(double v, double y);
conv
subpackage
Functions
convc1d convc1dcircular convc1dcircularinv convc1dinv convr1d convr1dcircular convr1dcircularinv convr1dinv
Examples
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:
56 of 430
10/25/2011 03:12 PM
It is assumed that A is zero at T<0, B is zero too. If one or functions have non-zero values at negative T's, you can still use subroutine - just shift its result correspondingly. both this
-- ALGLIB -Copyright 21.07.2009 by Bochkanov Sergey *************************************************************************/ void alglib::convc1d( complex_1d_array a, ae_int_t m, complex_1d_array b, ae_int_t n, complex_1d_array& r);
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 *************************************************************************/ void alglib::convc1dcircular( complex_1d_array s, ae_int_t m, complex_1d_array r, ae_int_t n, complex_1d_array& c);
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)
57 of 430
10/25/2011 03:12 PM
M B N convolved signal length array[0..N-1] - non-periodic response 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 *************************************************************************/ void alglib::convc1dcircularinv( complex_1d_array a, ae_int_t m, complex_1d_array b, ae_int_t n, complex_1d_array& r);
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 functions have non-zero values at negative T's, you can still use subroutine - just shift its result correspondingly. both this
-- ALGLIB -Copyright 21.07.2009 by Bochkanov Sergey *************************************************************************/ void alglib::convc1dinv( complex_1d_array a, ae_int_t m, complex_1d_array b, ae_int_t n, complex_1d_array& r);
58 of 430
10/25/2011 03:12 PM
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 functions have non-zero values at negative T's, you can still use subroutine - just shift its result correspondingly. both this
-- ALGLIB -Copyright 21.07.2009 by Bochkanov Sergey *************************************************************************/ void alglib::convr1d( real_1d_array a, ae_int_t m, real_1d_array b, ae_int_t n, real_1d_array& r);
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 *************************************************************************/ void alglib::convr1dcircular( real_1d_array s, ae_int_t m, real_1d_array r, ae_int_t n, real_1d_array& c);
59 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::convr1dcircularinv( real_1d_array a, ae_int_t m, real_1d_array b, ae_int_t n, real_1d_array& r);
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 functions have non-zero values at negative T's, you can still use subroutine - just shift its result correspondingly. both this
60 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 21.07.2009 by Bochkanov Sergey *************************************************************************/ void alglib::convr1dinv( real_1d_array a, ae_int_t m, real_1d_array b, ae_int_t n, real_1d_array& r);
corr
subpackage
Functions
corrc1d corrc1dcircular corrr1d corrr1dcircular
Examples
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 --
61 of 430
10/25/2011 03:12 PM
Copyright 21.07.2009 by Bochkanov Sergey *************************************************************************/ void alglib::corrc1d( complex_1d_array signal, ae_int_t n, complex_1d_array pattern, ae_int_t m, complex_1d_array& r);
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 *************************************************************************/ void alglib::corrc1dcircular( complex_1d_array signal, ae_int_t m, complex_1d_array pattern, ae_int_t n, complex_1d_array& c);
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").
62 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::corrr1d( real_1d_array signal, ae_int_t n, real_1d_array pattern, ae_int_t m, real_1d_array& r);
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 *************************************************************************/ void alglib::corrr1dcircular( real_1d_array signal, ae_int_t m,
63 of 430
10/25/2011 03:12 PM
real_1d_array pattern, ae_int_t n, real_1d_array& c);
correlationtests
Functions
subpackage
pearsoncorrelationsignific anc e spearmanrankcorrelationsignific anc e
Examples
pearsoncorrelationsignificance
function
/************************************************************************* Pearson's correlation coefficient significance test This test checks hypotheses about whether X and Y are continuous distributions having zero correlation or correlation is non-zero. samples of two whether their
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 LeftTail RightTail p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. 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 *************************************************************************/ void alglib::pearsoncorrelationsignificance( double r, ae_int_t n, double& bothtails, double& lefttail, double& righttail);
64 of 430
10/25/2011 03:12 PM
spearmanrankcorrelationsignificance
function
/************************************************************************* Spearman's rank correlation coefficient significance test This test checks hypotheses about whether X and Y are continuous distributions having zero correlation or correlation is non-zero. samples of two whether their
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 LeftTail RightTail p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. 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 *************************************************************************/ void alglib::spearmanrankcorrelationsignificance( double r, ae_int_t n, double& bothtails, double& lefttail, double& righttail);
dawson
Functions
subpackage
dawsonintegral
Examples
dawsonintegral
function
65 of 430
10/25/2011 03:12 PM
/************************************************************************* Dawson's Integral Approximates the integral x 2 dawsn(x) = exp( -x ) | | | | | 0 2 exp( t ) dt
Three different rational approximations are employed, for the intervals 0 to 3.25; 3.25 to 6.25; and 6.25 up. ACCURACY: arithmetic IEEE domain 0,10 Relative error: # trials peak 10000 6.9e-16 rms 1.0e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::dawsonintegral(double x);
densesolver
Classes
densesolverlsreport densesolverreport
subpackage
Functions
cmatrixlusolve cmatrixlusolvem cmatrixmixedsolve cmatrixmixedsolvem cmatrixsolve cmatrixsolvem hpdmatrixcholeskysolve hpdmatrixcholeskysolvem hpdmatrixsolve hpdmatrixsolvem rmatrixlusolve rmatrixlusolvem rmatrixmixedsolve rmatrixmixedsolvem rmatrixsolve rmatrixsolvels rmatrixsolvem spdmatrixcholeskysolve spdmatrixcholeskysolvem spdmatrixsolve spdmatrixsolvem
66 of 430
10/25/2011 03:12 PM
Examples
densesolverlsreport
class
/************************************************************************* *************************************************************************/ class densesolverlsreport { double r2; real_2d_array cx; ae_int_t n; ae_int_t k; };
densesolverreport
class
/************************************************************************* *************************************************************************/ class densesolverreport { double r1; double rinf; };
cmatrixlusolve
function
/************************************************************************* Dense solver. Same as RMatrixLUSolve(), but for complex matrices. 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. 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::cmatrixlusolve( complex_2d_array lua, integer_1d_array p, ae_int_t n,
67 of 430
10/25/2011 03:12 PM
complex_1d_array b, ae_int_t& info, densesolverreport& rep, complex_1d_array& x);
cmatrixlusolvem
function
/************************************************************************* Dense solver. Same as RMatrixLUSolveM(), but for complex matrices. 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. 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::cmatrixlusolvem( complex_2d_array lua, integer_1d_array p, ae_int_t n, complex_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, complex_2d_array& x);
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
68 of 430
10/25/2011 03:12 PM
B array[0..N-1], right part
OUTPUT PARAMETERS Info same as in RMatrixSolveM Rep same as in RMatrixSolveM X same as in RMatrixSolveM -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::cmatrixmixedsolve( complex_2d_array a, complex_2d_array lua, integer_1d_array p, ae_int_t n, complex_1d_array b, ae_int_t& info, densesolverreport& rep, complex_1d_array& x);
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], LUA array[0..N-1,0..N-1], P array[0..N-1], pivots N size of A B array[0..N-1,0..M-1], M right part size system matrix LU decomposition, CMatrixLU result array, CMatrixLU result right part
OUTPUT PARAMETERS Info same as in RMatrixSolveM Rep same as in RMatrixSolveM X same as in RMatrixSolveM -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::cmatrixmixedsolvem( complex_2d_array a, complex_2d_array lua, integer_1d_array p, ae_int_t n, complex_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, complex_2d_array& x);
cmatrixsolve
function
69 of 430
10/25/2011 03:12 PM
/************************************************************************* Dense solver. Same as RMatrixSolve(), but for complex matrices. Algorithm features: * automatic detection of degenerate cases * condition number estimation * iterative refinement * O(N^3) complexity 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::cmatrixsolve( complex_2d_array a, ae_int_t n, complex_1d_array b, ae_int_t& info, densesolverreport& rep, complex_1d_array& x);
cmatrixsolvem
function
/************************************************************************* Dense solver. Same as RMatrixSolveM(), but for complex matrices. Algorithm features: * automatic detection of degenerate cases * condition number estimation * iterative refinement * O(N^3+M*N^2) complexity 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::cmatrixsolvem( complex_2d_array a,
70 of 430
10/25/2011 03:12 PM
ae_int_t n, complex_2d_array b, ae_int_t m, bool rfs, ae_int_t& info, densesolverreport& rep, complex_2d_array& x);
hpdmatrixcholeskysolve
function
/************************************************************************* Dense solver. Same as RMatrixLUSolve(), but for HPD matrices represented by their Cholesky decomposition. 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. 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::hpdmatrixcholeskysolve( complex_2d_array cha, ae_int_t n, bool isupper, complex_1d_array b, ae_int_t& info, densesolverreport& rep, complex_1d_array& x);
hpdmatrixcholeskysolvem
function
/************************************************************************* Dense solver. Same as RMatrixLUSolveM(), but for HPD matrices represented by their Cholesky decomposition. Algorithm features: * automatic detection of degenerate cases * O(M*N^2) complexity * condition number estimation * matrix is represented by its upper or lower triangle
71 of 430
10/25/2011 03:12 PM
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. INPUT PARAMETERS CHA array[0..N-1,0..N-1], Cholesky decomposition, HPDMatrixCholesky 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::hpdmatrixcholeskysolvem( complex_2d_array cha, ae_int_t n, bool isupper, complex_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, complex_2d_array& x);
hpdmatrixsolve
function
/************************************************************************* Dense solver. Same as RMatrixSolve(), but for Hermitian positive definite matrices. 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. 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 Returns Rep same as X same as -- ALGLIB -in -3 in in RMatrixSolve for non-HPD matrices. RMatrixSolve RMatrixSolve
72 of 430
10/25/2011 03:12 PM
Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::hpdmatrixsolve( complex_2d_array a, ae_int_t n, bool isupper, complex_1d_array b, ae_int_t& info, densesolverreport& rep, complex_1d_array& x);
hpdmatrixsolvem
function
/************************************************************************* Dense solver. Same as RMatrixSolveM(), but for Hermitian positive definite matrices. 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. 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 Returns Rep same as X same as in -3 in in RMatrixSolve. for non-HPD matrices. RMatrixSolve RMatrixSolve
-- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::hpdmatrixsolvem( complex_2d_array a, ae_int_t n, bool isupper, complex_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, complex_2d_array& x);
rmatrixlusolve
function
/************************************************************************* Dense solver. This subroutine solves a system A*X=B, where A is NxN non-denegerate
73 of 430
10/25/2011 03:12 PM
real matrix given by its LU decomposition, X and B are NxM real matrices. 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. 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::rmatrixlusolve( real_2d_array lua, integer_1d_array p, ae_int_t n, real_1d_array b, ae_int_t& info, densesolverreport& rep, real_1d_array& x);
rmatrixlusolvem
function
/************************************************************************* Dense solver. Similar to RMatrixLUSolve() but solves task with multiple right parts (where b and x are NxM matrices). 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. 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve
74 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::rmatrixlusolvem( real_2d_array lua, integer_1d_array p, ae_int_t n, real_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, real_2d_array& x);
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 same as in RMatrixSolveM Rep same as in RMatrixSolveM X same as in RMatrixSolveM -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::rmatrixmixedsolve( real_2d_array a, real_2d_array lua, integer_1d_array p, ae_int_t n, real_1d_array b, ae_int_t& info, densesolverreport& rep, real_1d_array& x);
rmatrixmixedsolvem
function
/************************************************************************* Dense solver. Similar to RMatrixMixedSolve() but solves task with multiple right parts
75 of 430
10/25/2011 03:12 PM
(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], LUA array[0..N-1,0..N-1], P array[0..N-1], pivots N size of A B array[0..N-1,0..M-1], M right part size system matrix LU decomposition, RMatrixLU result array, RMatrixLU result right part
OUTPUT PARAMETERS Info same as in RMatrixSolveM Rep same as in RMatrixSolveM X same as in RMatrixSolveM -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::rmatrixmixedsolvem( real_2d_array a, real_2d_array lua, integer_1d_array p, ae_int_t n, real_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, real_2d_array& x);
rmatrixsolve
function
/************************************************************************* Dense solver. This subroutine solves a system real matrix, x and b are vectors. A*x=b, where A is NxN non-denegerate
Algorithm features: * automatic detection of degenerate cases * condition number estimation * iterative refinement * O(N^3) complexity 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 A is singular, or VERY close to 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 solver report, see below for more info
76 of 430
10/25/2011 03:12 PM
X array[0..N-1], it contains: * solution of A*x=b if A is non-singular (well-conditioned or ill-conditioned, but not very close to singular) * zeros, if A is singular or VERY close to singular (in this case Info=-3).
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 -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::rmatrixsolve( real_2d_array a, ae_int_t n, real_1d_array b, ae_int_t& info, densesolverreport& rep, real_1d_array& x);
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 of degenerate cases * iterative refinement * O(N^3) complexity 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 if A is non-singular (well-conditioned or ill-conditioned, but not very close to singular) * zeros, if A is singular or VERY close to singular (in this case Info=-3). SOLVER REPORT
77 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::rmatrixsolvels( real_2d_array a, ae_int_t nrows, ae_int_t ncols, real_1d_array b, double threshold, ae_int_t& info, densesolverlsreport& rep, real_1d_array& x);
rmatrixsolvem
function
/************************************************************************* Dense solver. Similar to RMatrixSolve() but solves task with multiple right parts (where b and x are NxM matrices). Algorithm features: * automatic detection of degenerate cases * condition number estimation * optional iterative refinement * O(N^3+M*N^2) complexity 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::rmatrixsolvem( real_2d_array a, ae_int_t n, real_2d_array b, ae_int_t m, bool rfs, ae_int_t& info, densesolverreport& rep, real_2d_array& x);
78 of 430
10/25/2011 03:12 PM
spdmatrixcholeskysolve
function
/************************************************************************* Dense solver. Same as RMatrixLUSolve(), but for SPD matrices represented by their Cholesky decomposition. 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. 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 same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spdmatrixcholeskysolve( real_2d_array cha, ae_int_t n, bool isupper, real_1d_array b, ae_int_t& info, densesolverreport& rep, real_1d_array& x);
spdmatrixcholeskysolvem
function
/************************************************************************* Dense solver. Same as RMatrixLUSolveM(), but for SPD matrices represented by their Cholesky decomposition. 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. INPUT PARAMETERS
79 of 430
10/25/2011 03:12 PM
CHA N IsUpper B M array[0..N-1,0..N-1], Cholesky decomposition, SPDMatrixCholesky result size of CHA what half of CHA is provided array[0..N-1,0..M-1], right part right part size
OUTPUT PARAMETERS Info same as in RMatrixSolve Rep same as in RMatrixSolve X same as in RMatrixSolve -- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spdmatrixcholeskysolvem( real_2d_array cha, ae_int_t n, bool isupper, real_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, real_2d_array& x);
spdmatrixsolve
function
/************************************************************************* Dense solver. Same as RMatrixSolve(), but for SPD matrices. 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. 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 Returns Rep same as X same as in -3 in in RMatrixSolve for non-SPD matrices. RMatrixSolve RMatrixSolve
-- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spdmatrixsolve( real_2d_array a, ae_int_t n, bool isupper, real_1d_array b, ae_int_t& info,
80 of 430
10/25/2011 03:12 PM
densesolverreport& rep, real_1d_array& x);
spdmatrixsolvem
function
/************************************************************************* Dense solver. Same as RMatrixSolveM(), but for symmetric positive definite matrices. 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. 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 Returns Rep same as X same as in -3 in in RMatrixSolve. for non-SPD matrices. RMatrixSolve RMatrixSolve
-- ALGLIB -Copyright 27.01.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spdmatrixsolvem( real_2d_array a, ae_int_t n, bool isupper, real_2d_array b, ae_int_t m, ae_int_t& info, densesolverreport& rep, real_2d_array& x);
dforest
Classes
decisionforest dfreport
subpackage
Functions
dfavgce dfavgerror dfavgrelerror
81 of 430
10/25/2011 03:12 PM
dfbuildrandomdec isionforest dfbuildrandomdec isionforestx1 dfprocess dfprocessi dfrelclserror dfrmserror dfserialize dfunserialize
Examples
decisionforest
class
/************************************************************************* *************************************************************************/ class decisionforest { };
dfreport
class
/************************************************************************* *************************************************************************/ class dfreport { double relclserror; double avgce; double rmserror; double avgerror; double avgrelerror; double oobrelclserror; double oobavgce; double oobrmserror; double oobavgerror; double oobavgrelerror; };
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 *************************************************************************/ double alglib::dfavgce(
82 of 430
10/25/2011 03:12 PM
decisionforest df, real_2d_array xy, ae_int_t 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 *************************************************************************/ double alglib::dfavgerror( decisionforest df, real_2d_array xy, ae_int_t 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 *************************************************************************/ double alglib::dfavgrelerror( decisionforest df, real_2d_array xy, ae_int_t npoints);
dfbuildrandomdecisionforest
function
/************************************************************************* This subroutine builds random decision forest. INPUT PARAMETERS: XY NPoints training set training set size, NPoints>=1
83 of 430
10/25/2011 03:12 PM
NVars NClasses number of independent variables, NVars>=1 task type: * NClasses=1 - regression task with one dependent variable * NClasses>1 - classification task with NClasses classes. number of trees in a forest, NTrees>=1. recommended values: 50-100. percent of a training set used to build individual trees. 0<R<=1. recommended values: 0.1 <= R <= 0.66. 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 model built training report, contains error on a training set and out-of-bag estimates of generalization error.
NTrees R
OUTPUT PARAMETERS: Info -
DF Rep
-- ALGLIB -Copyright 19.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::dfbuildrandomdecisionforest( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t nclasses, ae_int_t ntrees, double r, ae_int_t& info, decisionforest& df, dfreport& rep);
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 NPoints NVars NClasses training set training set size, NPoints>=1 number of independent variables, NVars>=1 task type: * NClasses=1 - regression task with one dependent variable * NClasses>1 - classification task with NClasses classes. number of trees in a forest, NTrees>=1. recommended values: 50-100. number of variables used when choosing best split percent of a training set used to build individual trees. 0<R<=1. recommended values: 0.1 <= R <= 0.66.
NTrees NRndVars R
OUTPUT PARAMETERS:
84 of 430
10/25/2011 03:12 PM
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 model built training report, contains error on a training set and out-of-bag estimates of generalization error.
DF Rep
-- ALGLIB -Copyright 19.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::dfbuildrandomdecisionforestx1( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t nclasses, ae_int_t ntrees, ae_int_t nrndvars, double r, ae_int_t& info, decisionforest& df, dfreport& rep);
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 *************************************************************************/ void alglib::dfprocess( decisionforest df, real_1d_array x, real_1d_array& 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 --
85 of 430
10/25/2011 03:12 PM
Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::dfprocessi( decisionforest df, real_1d_array x, real_1d_array& y);
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 *************************************************************************/ double alglib::dfrelclserror( decisionforest df, real_2d_array xy, ae_int_t 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 *************************************************************************/ double alglib::dfrmserror( decisionforest df, real_2d_array xy, ae_int_t npoints);
dfserialize
function
/************************************************************************* This function serializes data structure to string.
86 of 430
10/25/2011 03:12 PM
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. *************************************************************************/ void dfserialize(decisionforest &obj, std::string &s_out);
dfunserialize
function
/************************************************************************* This function unserializes data structure from string. *************************************************************************/ void dfunserialize(std::string &s_in, decisionforest &obj);
elliptic
Functions
subpackage
ellipticintegrale ellipticintegralk ellipticintegralkhighprec ision incompleteelliptic integrale incompleteelliptic integralk
Examples
ellipticintegrale
function
/************************************************************************* Complete elliptic integral of the second kind Approximates the integral pi/2 | | 2 | sqrt( 1 - m sin t ) dt | | 0
E(m)
using the approximation P(x) x log x Q(x).
87 of 430
10/25/2011 03:12 PM
ACCURACY: arithmetic IEEE domain 0, 1 Relative error: # trials peak 10000 2.1e-16 rms 7.3e-17
Cephes Math Library, Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::ellipticintegrale(double m);
ellipticintegralk
function
/************************************************************************* Complete elliptic integral of the first kind Approximates the integral
K(m)
pi/2 | | | dt | -----------------| 2 | | sqrt( 1 - m sin t ) 0
using the approximation P(x) ACCURACY: arithmetic IEEE domain 0,1 Relative error: # trials peak 30000 2.5e-16 rms 6.8e-17 log x Q(x).
Cephes Math Library, Release 2.8: June, 2000 Copyright 1984, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::ellipticintegralk(double m);
ellipticintegralkhighprecision
function
/************************************************************************* Complete elliptic integral of the first kind Approximates the integral
K(m)
pi/2 | | | dt | -----------------| 2
88 of 430
10/25/2011 03:12 PM
| | 0 sqrt( 1 - m sin t )
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: arithmetic IEEE domain 0,1 Relative error: # trials peak 30000 2.5e-16 rms 6.8e-17
Cephes *************************************************************************/ double alglib::ellipticintegralkhighprecision(double m1);
incompleteellipticintegrale
function
/************************************************************************* Incomplete elliptic integral of the second kind Approximates the integral phi | | | = | | | | 0
E(phi_\m)
2 sqrt( 1 - m sin t ) dt
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 *************************************************************************/ double alglib::incompleteellipticintegrale(double phi, double m);
incompleteellipticintegralk
function
89 of 430
10/25/2011 03:12 PM
/************************************************************************* Incomplete elliptic integral of the first kind F(phi|m) Approximates the integral
F(phi_\m)
phi | | | = | | | | 0
dt -----------------2 sqrt( 1 - m sin t )
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. arithmetic IEEE domain -10,10 Relative error: # trials peak 200000 7.4e-16 rms 1.0e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::incompleteellipticintegralk(double phi, double m);
evd
subpackage
Functions
hmatrixevd hmatrixevdi hmatrixevdr rmatrixevd smatrixevd smatrixevdi smatrixevdr smatrixtdevd smatrixtdevdi smatrixtdevdr
Examples
hmatrixevd
function
/************************************************************************* Finding the eigenvalues and eigenvectors of a Hermitian matrix
90 of 430
10/25/2011 03:12 PM
The algorithm finds eigen pairs of a Hermitian matrix by real tridiagonal form and using the QL/QR algorithm. reducing it to
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 hasnt 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 a complex number L, such that |L|=1. multiplication by
-- ALGLIB -Copyright 2005, 23 March 2007 by Bochkanov Sergey *************************************************************************/ bool alglib::hmatrixevd( complex_2d_array a, ae_int_t n, ae_int_t zneeded, bool isupper, real_1d_array& d, complex_2d_array& z);
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:
91 of 430
10/25/2011 03:12 PM
W Z array of the eigenvalues found. Array whose index ranges within [0..I2-I1]. if ZNeeded is equal to: * 0, Z hasnt 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 a complex number L, such as |L|=1. by
-- ALGLIB -Copyright 07.01.2006, 24.03.2007 by Bochkanov Sergey. *************************************************************************/ bool alglib::hmatrixevdi( complex_2d_array a, ae_int_t n, ae_int_t zneeded, bool isupper, ae_int_t i1, ae_int_t i2, real_1d_array& w, complex_2d_array& z);
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 hasnt changed; * 1, Z contains eigenvectors. Array whose indexes range within [0..N-1, 0..M-1].
92 of 430
10/25/2011 03:12 PM
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 a complex number L, such as |L|=1. by
-- ALGLIB -Copyright 07.01.2006, 24.03.2007 by Bochkanov Sergey. *************************************************************************/ bool alglib::hmatrixevdr( complex_2d_array a, ae_int_t n, ae_int_t zneeded, bool isupper, double b1, double b2, ae_int_t& m, real_1d_array& w, complex_2d_array& z);
rmatrixevd
function
/************************************************************************* Finding eigenvalues and eigenvectors of a general matrix 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.
93 of 430
10/25/2011 03:12 PM
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. *************************************************************************/ bool alglib::rmatrixevd( real_2d_array a, ae_int_t n, ae_int_t vneeded, real_1d_array& wr, real_1d_array& wi, real_2d_array& vl, real_2d_array& vr);
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. 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:
94 of 430
10/25/2011 03:12 PM
* 0, the eigenvectors are not returned; * 1, the eigenvectors are returned. storage format.
IsUpper -
Output parameters: D eigenvalues in ascending order. Array whose index ranges within [0..N-1]. Z if ZNeeded is equal to: * 0, Z hasnt 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 *************************************************************************/ bool alglib::smatrixevd( real_2d_array a, ae_int_t n, ae_int_t zneeded, bool isupper, real_1d_array& d, real_2d_array& z);
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 hasnt 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.
95 of 430
10/25/2011 03:12 PM
In that case, the eigenvalues and eigenvectors are not returned. -- ALGLIB -Copyright 07.01.2006 by Bochkanov Sergey *************************************************************************/ bool alglib::smatrixevdi( real_2d_array a, ae_int_t n, ae_int_t zneeded, bool isupper, ae_int_t i1, ae_int_t i2, real_1d_array& w, real_2d_array& z);
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 hasnt 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 *************************************************************************/ bool alglib::smatrixevdr( real_2d_array a, ae_int_t n, ae_int_t zneeded, bool isupper,
96 of 430
10/25/2011 03:12 PM
double b1, double b2, ae_int_t& m, real_1d_array& w, real_2d_array& z);
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. 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 hasnt 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 *************************************************************************/ bool alglib::smatrixtdevd( real_1d_array& d, real_1d_array e, ae_int_t n, ae_int_t zneeded,
97 of 430
10/25/2011 03:12 PM
real_2d_array& 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 *************************************************************************/ bool alglib::smatrixtdevdi( real_1d_array& d, real_1d_array e, ae_int_t n, ae_int_t zneeded,
98 of 430
10/25/2011 03:12 PM
ae_int_t i1, ae_int_t i2, real_2d_array& 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 *************************************************************************/ bool alglib::smatrixtdevdr( real_1d_array& d, real_1d_array e,
99 of 430
10/25/2011 03:12 PM
ae_int_t n, ae_int_t zneeded, double a, double b, ae_int_t& m, real_2d_array& z);
expintegrals
Functions
exponentialintegralei exponentialintegralen
subpackage
Examples
exponentialintegralei
function
/************************************************************************* Exponential integral Ei(x) x Ei(x) = | | -|| | -inf t e --t dt .
Not defined for x <= 0. See also expn.c.
ACCURACY: arithmetic IEEE domain 0,100 Relative error: # trials peak 50000 8.6e-16 rms 1.3e-16
Cephes Math Library Release 2.8: May, 1999 Copyright 1999 by Stephen L. Moshier *************************************************************************/ double alglib::exponentialintegralei(double x);
exponentialintegralen
function
/************************************************************************* Exponential integral En(x) Evaluates the exponential integral inf. | | |
-xt e
100 of 430
10/25/2011 03:12 PM
E (x) n = | | | | 1 ---n t dt.
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: arithmetic IEEE domain 0, 30 Relative error: # trials peak 10000 1.7e-15 rms 3.6e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1985, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::exponentialintegralen(double x, ae_int_t n);
fdistr
Functions
subpackage
fcdistribution fdistribution invfdistribution
Examples
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. | | a-1 b-1 | t (1-t) dt | | x
1-P(x)
1 -----B(a,b)
The incomplete beta integral is used, according to the formula P(x) = incbet( df2/2, df1/2, (df2/(df2 + df1*x) ).
101 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ double alglib::fcdistribution(ae_int_t a, ae_int_t b, double 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). arithmetic IEEE IEEE IEEE IEEE x domain 0,1 1,5 0,1 1,5 a,b domain 0,100 0,100 1,10000 1,10000 # trials 100000 100000 100000 100000 Relative error: peak rms 9.8e-15 1.7e-15 6.5e-15 3.5e-16 2.2e-11 3.3e-12 1.1e-11 1.7e-13
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::fdistribution(ae_int_t a, ae_int_t b, double 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.
102 of 430
10/25/2011 03:12 PM
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 arithmetic domain # trials For p between .001 and 1: IEEE 1,100 100000 IEEE 1,10000 100000 For p between 10^-6 and 10^-3: IEEE 1,100 50000 IEEE 1,10000 50000 Relative error: peak rms 8.3e-15 2.1e-11 1.3e-12 3.0e-12 4.7e-16 1.4e-13 8.4e-15 4.8e-14
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::invfdistribution(ae_int_t a, ae_int_t b, double y);
fft
subpackage
Functions
fftc1d fftc1dinv fftr1d fftr1dinv
Examples
fft_complex_d1 fft_complex_d2 fft_real_d1 fft_real_d2 Complex FFT: simple example Complex FFT: advanc ed example Real FFT: simple example Real FFT: advanc ed example
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.
103 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::fftc1d(complex_1d_array& a); void alglib::fftc1d(complex_1d_array& a, ae_int_t n); Examples: [1] [2]
fftc1dinv
function
/************************************************************************* 1-dimensional complex inverse FFT. Array size N may be arbitrary number (composite or prime). O(N*logN) complexity for any N (composite or prime). Algorithm has
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 *************************************************************************/ void alglib::fftc1dinv(complex_1d_array& a); void alglib::fftc1dinv(complex_1d_array& a, ae_int_t n); Examples: [1] [2]
fftr1d
function
/************************************************************************* 1-dimensional real FFT. Algorithm has O(N*logN) complexity for any N (composite or prime). INPUT PARAMETERS
104 of 430
10/25/2011 03:12 PM
A N array[0..N-1] - real function to be transformed 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 *************************************************************************/ void alglib::fftr1d(real_1d_array a, complex_1d_array& f); void alglib::fftr1d(real_1d_array a, ae_int_t n, complex_1d_array& f); 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 *************************************************************************/ void alglib::fftr1dinv(complex_1d_array f, real_1d_array& a); void alglib::fftr1dinv(complex_1d_array f, ae_int_t n, real_1d_array& a);
105 of 430
10/25/2011 03:12 PM
Examples: [1] [2]
fft_complex_d1 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "fasttransforms.h"
using namespace alglib; int main(int argc, char **argv) { // // first we demonstrate forward FFT: // [1i,1i,1i,1i] is converted to [4i, 0, 0, 0] // complex_1d_array z = "[1i,1i,1i,1i]"; fftc1d(z); printf("%s\n", z.tostring(3).c_str()); // EXPECTED: [4i,0,0,0] // // now we convert [4i, 0, 0, 0] back to [1i,1i,1i,1i] // with backward FFT // fftc1dinv(z); printf("%s\n", z.tostring(3).c_str()); // EXPECTED: [1i,1i,1i,1i] return 0; }
fft_complex_d2 example
using namespace alglib; int main(int argc, char **argv) { // // first we demonstrate forward FFT: // [0,1,0,1i] is converted to [1+1i, -1-1i, -1-1i, 1+1i] // complex_1d_array z = "[0,1,0,1i]"; fftc1d(z); printf("%s\n", z.tostring(3).c_str()); // EXPECTED: [1+1i, -1-1i, -1-1i, 1+1i] // // now we convert result back with backward FFT // fftc1dinv(z); printf("%s\n", z.tostring(3).c_str()); // EXPECTED: [0,1,0,1i] return 0; }
106 of 430
10/25/2011 03:12 PM
fft_real_d1 example
using namespace alglib; int main(int argc, char **argv) { // // first we demonstrate forward FFT: // [1,1,1,1] is converted to [4, 0, 0, 0] // real_1d_array x = "[1,1,1,1]"; complex_1d_array f; real_1d_array x2; fftr1d(x, f); printf("%s\n", f.tostring(3).c_str()); // EXPECTED: [4,0,0,0] // // now we convert [4, 0, 0, 0] back to [1,1,1,1] // with backward FFT // fftr1dinv(f, x2); printf("%s\n", x2.tostring(3).c_str()); // EXPECTED: [1,1,1,1] return 0; }
fft_real_d2 example
using namespace alglib; int main(int argc, char **argv) { // // 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]) // real_1d_array x = "[1,2,3,4]"; complex_1d_array f; real_1d_array x2;
107 of 430
10/25/2011 03:12 PM
fftr1d(x, f); printf("%s\n", f.tostring(3).c_str()); // EXPECTED: [10, -2+2i, -2, -2-2i] // // now we convert [10, -2+2i, -2, -2-2i] back to [1,2,3,4] // fftr1dinv(f, x2); printf("%s\n", x2.tostring(3).c_str()); // 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+2i, -2]"; fftr1dinv(f, 4, x2); printf("%s\n", x2.tostring(3).c_str()); // EXPECTED: [1,2,3,4] return 0; }
fht
subpackage
Functions
fhtr1d fhtr1dinv
Examples
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 *************************************************************************/ void alglib::fhtr1d(real_1d_array& a, ae_int_t n);
108 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::fhtr1dinv(real_1d_array& a, ae_int_t n);
fresnel
Functions
fresnelintegral
subpackage
Examples
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 )
109 of 430
10/25/2011 03:12 PM
S(x) = 0.5 - f(x) cos( pi/2 x**2 ) - g(x) sin( pi/2 x**2 )
ACCURACY: Relative error. Arithmetic IEEE IEEE function S(x) C(x) domain 0, 10 0, 10 # trials 10000 10000 peak 2.0e-15 1.8e-15 rms 3.2e-16 3.3e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1989, 2000 by Stephen L. Moshier *************************************************************************/ void alglib::fresnelintegral(double x, double& c, double& s);
gammafunc
Functions
gammafunction lngamma
subpackage
Examples
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 IEEE -170,-33 IEEE -33, 33 IEEE 33, 171.6 # trials 20000 20000 20000 peak 2.3e-15 9.4e-16 2.3e-15 rms 3.3e-16 2.2e-16 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). *************************************************************************/ double alglib::gammafunction(double x);
lngamma
function
/************************************************************************* Natural logarithm of gamma function Input parameters:
110 of 430
10/25/2011 03:12 PM
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 IEEE 0, 3 28000 IEEE 2.718, 2.556e305 40000 The error criterion was relative when the was greater than one but absolute when it peak rms 5.4e-16 1.1e-16 3.5e-16 8.3e-17 function magnitude 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). *************************************************************************/ double alglib::lngamma(double x, double& sgngam);
gkq
subpackage
Functions
gkqgenerategaussjac obi gkqgenerategausslegendre gkqgeneraterec gkqlegendrecalc gkqlegendretbl
Examples
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 Alpha Beta OUTPUT PARAMETERS: Info number of Kronrod nodes, must be odd number, >=3. power-law coefficient, Alpha>-1 power-law coefficient, Beta>-1 error code: * -5 no real and positive Gauss-Kronrod formula can
111 of 430
10/25/2011 03:12 PM
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 array[0..N-1] - array of quadrature nodes, ordered in ascending order. array[0..N-1] - Kronrod weights array[0..N-1] - Gauss weights (interleaved with zeros corresponding to extended Kronrod nodes).
X WKronrod WGauss
-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/ void alglib::gkqgenerategaussjacobi( ae_int_t n, double alpha, double beta, ae_int_t& info, real_1d_array& x, real_1d_array& wkronrod, real_1d_array& wgauss);
gkqgenerategausslegendre
function
/************************************************************************* Returns Gauss and Gauss-Kronrod nodes/weights for Gauss-Legendre quadrature with N points. GKQLegendreCalc (calculation) or GKQLegendreTbl (precomputed used depending on machine precision and number of nodes. INPUT PARAMETERS: N OUTPUT PARAMETERS: Info table) is
number of Kronrod nodes, must be odd number, >=3. 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 array[0..N-1] - array of quadrature nodes, ordered in ascending order. array[0..N-1] - Kronrod weights array[0..N-1] - Gauss weights (interleaved with zeros corresponding to extended Kronrod nodes).
X WKronrod WGauss
-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/
112 of 430
10/25/2011 03:12 PM
void alglib::gkqgenerategausslegendre( ae_int_t n, ae_int_t& info, real_1d_array& x, real_1d_array& wkronrod, real_1d_array& wgauss);
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) P0(x) Pn+1(x) = = = 0 1 (x-alpha(n))*Pn(x)
beta(n)*Pn-1(x)
and zero moment Mu0 Mu0 = integral(W(x)dx,a,b) INPUT PARAMETERS: Alpha Beta Mu0 N
alpha coefficients, array[0..floor(3*K/2)]. beta coefficients, array[0..ceil(3*K/2)]. Beta[0] is not used and may be arbitrary. Beta[I]>0. zeroth moment of the weight function. number of nodes of the Gauss-Kronrod quadrature formula, N >= 3, N = 2*K+1. 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 array[0..N-1] - array of quadrature nodes, in ascending order. array[0..N-1] - Kronrod weights array[0..N-1] - Gauss weights (interleaved with zeros corresponding to extended Kronrod nodes).
X WKronrod WGauss
-- ALGLIB -Copyright 08.05.2009 by Bochkanov Sergey *************************************************************************/ void alglib::gkqgeneraterec( real_1d_array alpha, real_1d_array beta, double mu0, ae_int_t n, ae_int_t& info, real_1d_array& x,
113 of 430
10/25/2011 03:12 PM
real_1d_array& wkronrod, real_1d_array& wgauss);
gkqlegendrecalc
function
/************************************************************************* Returns Gauss and Gauss-Kronrod nodes for quadrature with N points. Reduction to tridiagonal eigenproblem is used. INPUT PARAMETERS: N OUTPUT PARAMETERS: Info number of Kronrod nodes, must be odd number, >=3. 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 array[0..N-1] - array of quadrature nodes, ordered in ascending order. array[0..N-1] - Kronrod weights array[0..N-1] - Gauss weights (interleaved with zeros corresponding to extended Kronrod nodes).
X WKronrod WGauss
-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/ void alglib::gkqlegendrecalc( ae_int_t n, ae_int_t& info, real_1d_array& x, real_1d_array& wkronrod, real_1d_array& wgauss);
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 OUTPUT PARAMETERS: X WKronrod WGauss number of Kronrod nodes. N can be 15, 21, 31, 41, 51, 61. array[0..N-1] - array of quadrature nodes, ordered in ascending order. array[0..N-1] - Kronrod weights array[0..N-1] - Gauss weights (interleaved with zeros corresponding to extended Kronrod nodes).
-- ALGLIB --
114 of 430
10/25/2011 03:12 PM
Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/ void alglib::gkqlegendretbl( ae_int_t n, real_1d_array& x, real_1d_array& wkronrod, real_1d_array& wgauss, double& eps);
gq
subpackage
Functions
gqgenerategausshermite gqgenerategaussjac obi gqgenerategausslaguerre gqgenerategausslegendre gqgenerategausslobattorec gqgenerategaussradaurec gqgeneraterec
Examples
gqgenerategausshermite
function
/************************************************************************* Returns nodes/weights for Gauss-Hermite quadrature on (-inf,+inf) with weight function W(x)=Exp(-x*x) INPUT PARAMETERS: N OUTPUT PARAMETERS: Info number of nodes, >=1 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 array[0..N-1] - array of quadrature nodes, in ascending order. array[0..N-1] - array of quadrature weights.
X W
-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/ void alglib::gqgenerategausshermite( ae_int_t n, ae_int_t& info, real_1d_array& x, real_1d_array& w);
gqgenerategaussjacobi
function
115 of 430
10/25/2011 03:12 PM
/************************************************************************* 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 Alpha Beta OUTPUT PARAMETERS: Info number of nodes, >=1 power-law coefficient, Alpha>-1 power-law coefficient, Beta>-1 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 array[0..N-1] - array of quadrature nodes, in ascending order. array[0..N-1] - array of quadrature weights.
X W
-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/ void alglib::gqgenerategaussjacobi( ae_int_t n, double alpha, double beta, ae_int_t& info, real_1d_array& x, real_1d_array& w);
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 Alpha OUTPUT PARAMETERS: Info number of nodes, >=1 power-law coefficient, Alpha>-1 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 array[0..N-1] - array of quadrature nodes, in ascending order. array[0..N-1] - array of quadrature weights.
X W
-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey
116 of 430
10/25/2011 03:12 PM
*************************************************************************/ void alglib::gqgenerategausslaguerre( ae_int_t n, double alpha, ae_int_t& info, real_1d_array& x, real_1d_array& w);
gqgenerategausslegendre
function
/************************************************************************* Returns nodes/weights for Gauss-Legendre quadrature on [-1,1] with N nodes. INPUT PARAMETERS: N OUTPUT PARAMETERS: Info number of nodes, >=1 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 array[0..N-1] - array of quadrature nodes, in ascending order. array[0..N-1] - array of quadrature weights.
X W
-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/ void alglib::gqgenerategausslegendre( ae_int_t n, ae_int_t& info, real_1d_array& x, real_1d_array& w);
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) P0(x) Pn+1(x) = = = 0 1 (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.
117 of 430
10/25/2011 03:12 PM
Zero-indexed element is not used, may be arbitrary. Beta[I]>0 zeroth moment of the weighting function. left boundary of the integration interval. right boundary of the integration interval. number of nodes of the quadrature formula, N>=3 (including the left and right boundary nodes).
Mu0 A B N
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 *************************************************************************/ void alglib::gqgenerategausslobattorec( real_1d_array alpha, real_1d_array beta, double mu0, double a, double b, ae_int_t n, ae_int_t& info, real_1d_array& x, real_1d_array& w);
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) P0(x) Pn+1(x) = = = 0 1 (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
118 of 430
10/25/2011 03:12 PM
* -2 Beta[i]<=0 * -1 incorrect N was passed * 1 OK array[0..N-1] - array of quadrature nodes, in ascending order. array[0..N-1] - array of quadrature weights.
X W
-- ALGLIB -Copyright 2005-2009 by Bochkanov Sergey *************************************************************************/ void alglib::gqgenerategaussradaurec( real_1d_array alpha, real_1d_array beta, double mu0, double a, ae_int_t n, ae_int_t& info, real_1d_array& x, real_1d_array& w);
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) P0(x) Pn+1(x) = = = 0 1 (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 *************************************************************************/ void alglib::gqgeneraterec( real_1d_array alpha, real_1d_array beta,
119 of 430
10/25/2011 03:12 PM
double mu0, ae_int_t n, ae_int_t& info, real_1d_array& x, real_1d_array& w);
hermite
Functions
subpackage
hermitecalculate hermitecoefficients hermitesum
Examples
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 *************************************************************************/ double alglib::hermitecalculate(ae_int_t n, double 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 *************************************************************************/ void alglib::hermitecoefficients(ae_int_t n, real_1d_array& c);
hermitesum
function
/************************************************************************* Summation of Hermite polynomials using Clenshaws recurrence formula. This routine calculates c[0]*H0(x) + c[1]*H1(x) + ... + c[N]*HN(x) Parameters: n degree, n>=0 x argument
120 of 430
10/25/2011 03:12 PM
Result: the value of the Hermite polynomial at x *************************************************************************/ double alglib::hermitesum(real_1d_array c, ae_int_t n, double x);
hqrnd
Classes
hqrndstate
subpackage
Functions
hqrndexponential hqrndnormal hqrndnormal2 hqrndrandomize hqrndseed hqrnduniformi hqrnduniformr hqrndunit2
Examples
hqrndstate
class
/************************************************************************* Portable high quality random number generator state. Initialized with HQRNDRandomize() or HQRNDSeed(). Fields: S1, S2 V MagicV seed values precomputed value 'magic' value used to determine whether State structure was correctly initialized. *************************************************************************/ class hqrndstate { }; -
hqrndexponential
function
/************************************************************************* Random number generator: exponential distribution State structure must be initialized with HQRNDRandomize() or HQRNDSeed(). -- ALGLIB -Copyright 11.08.2007 by Bochkanov Sergey *************************************************************************/ double alglib::hqrndexponential(hqrndstate state, double lambdav);
121 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ double alglib::hqrndnormal(hqrndstate 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 *************************************************************************/ void alglib::hqrndnormal2(hqrndstate state, double& x1, double& x2);
hqrndrandomize
function
/************************************************************************* HQRNDState initialization with random values which come from standard RNG. -- ALGLIB -Copyright 02.12.2009 by Bochkanov Sergey *************************************************************************/ void alglib::hqrndrandomize(hqrndstate& state);
hqrndseed
function
/************************************************************************* HQRNDState initialization with seed values -- ALGLIB -Copyright 02.12.2009 by Bochkanov Sergey *************************************************************************/ void alglib::hqrndseed(ae_int_t s1, ae_int_t s2, hqrndstate& state);
hqrnduniformi
function
/************************************************************************* This function generates random integer number in [0, N)
122 of 430
10/25/2011 03:12 PM
1. N must be less than HQRNDMax-1. 2. State structure must be initialized with HQRNDRandomize() or HQRNDSeed() -- ALGLIB -Copyright 02.12.2009 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::hqrnduniformi(hqrndstate state, ae_int_t 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 *************************************************************************/ double alglib::hqrnduniformr(hqrndstate 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 *************************************************************************/ void alglib::hqrndunit2(hqrndstate state, double& x, double& y);
ibetaf
Functions
subpackage
incompletebeta invincompletebeta
Examples
incompletebeta
function
/************************************************************************* Incomplete beta integral Returns incomplete beta integral of the arguments, evaluated from zero to x. The function is defined as | (a+b) x | | a-1 b-1
123 of 430
10/25/2011 03:12 PM
----------| (a) | (b) | | | 0 t (1-t) dt.
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 *************************************************************************/ double alglib::incompletebeta(double a, double b, double 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
124 of 430
10/25/2011 03:12 PM
Copyright 1984, 1996, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::invincompletebeta(double a, double b, double y);
idwint
Classes
subpackage
idwinterpolant
Functions
idwbuildmodifiedshepard idwbuildmodifiedshepardr idwbuildnoisy idwcalc
Examples
idwinterpolant
class
/************************************************************************* IDW interpolant. *************************************************************************/ class idwinterpolant { };
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.
125 of 430
10/25/2011 03:12 PM
Values less than this threshold will be silently increased. 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
NW
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 *************************************************************************/ void alglib::idwbuildmodifiedshepard( real_2d_array xy, ae_int_t n, ae_int_t nx, ae_int_t d, ae_int_t nq, ae_int_t nw, idwinterpolant& z);
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
126 of 430
10/25/2011 03:12 PM
IDWKMin closest ones, so that continuity properties of preserved even far from points. interpolant are
-- ALGLIB PROJECT -Copyright 11.04.2010 by Bochkanov Sergey *************************************************************************/ void alglib::idwbuildmodifiedshepardr( real_2d_array xy, ae_int_t n, ae_int_t nx, double r, idwinterpolant& z);
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
127 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::idwbuildnoisy( real_2d_array xy, ae_int_t n, ae_int_t nx, ae_int_t d, ae_int_t nq, ae_int_t nw, idwinterpolant& z);
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 *************************************************************************/ double alglib::idwcalc(idwinterpolant z, real_1d_array x);
igammaf
Functions
subpackage
incompletegamma incompletegammac invincompletegammac
Examples
incompletegamma
function
/*************************************************************************
128 of 430
10/25/2011 03:12 PM
Incomplete gamma integral The function is defined by x igam(a,x) = 1 ----| (a) | | -t a-1 | e t dt. | | 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: arithmetic IEEE IEEE domain 0,30 0,100 Relative error: # trials peak 200000 3.6e-14 300000 9.9e-14 rms 2.9e-15 1.5e-14
Cephes Math Library Release 2.8: June, 2000 Copyright 1985, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::incompletegamma(double a, double x);
incompletegammac
function
/************************************************************************* Complemented incomplete gamma integral The function is defined by igamc(a,x) = 1 - igam(a,x) inf. | | -t a-1 | e t dt. | | x
1 ----| (a)
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 arithmetic domain domain IEEE 0.5,100 0,100 IEEE 0.01,0.5 0,100 Relative error: peak rms 1.9e-14 1.7e-15 1.4e-13 1.6e-15
# trials 200000 200000
129 of 430
10/25/2011 03:12 PM
Cephes Math Library Release 2.8: June, 2000 Copyright 1985, 1987, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::incompletegammac(double a, double 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 arithmetic domain IEEE 0.5,100 IEEE 0.01,0.5 IEEE 0.5,10000 p domain 0,0.5 0,0.5 0,0.5 # trials 100000 100000 20000 Relative error: peak rms 1.0e-14 1.7e-15 9.0e-14 3.4e-15 2.3e-13 3.8e-14
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::invincompletegammac(double a, double y0);
inverseupdate
Functions
rmatrixinvupdatec olumn rmatrixinvupdaterow rmatrixinvupdatesimple rmatrixinvupdateuv
subpackage
Examples
130 of 430
10/25/2011 03:12 PM
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 N UpdColumn U inverse of matrix A. Array whose indexes range within [0..N-1, 0..N-1]. size of matrix A. the column of A whose vector U was added. 0 <= UpdColumn <= N-1 the vector to be added to a column. Array whose index ranges within [0..N-1]. inverse of modified matrix A.
Output parameters: InvA -
-- ALGLIB -Copyright 2005 by Bochkanov Sergey *************************************************************************/ void alglib::rmatrixinvupdatecolumn( real_2d_array& inva, ae_int_t n, ae_int_t updcolumn, real_1d_array 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 *************************************************************************/ void alglib::rmatrixinvupdaterow( real_2d_array& inva, ae_int_t n, ae_int_t updrow, real_1d_array v);
rmatrixinvupdatesimple
function
10/25/2011 03:12 PM
131 of 430
/************************************************************************* 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 *************************************************************************/ void alglib::rmatrixinvupdatesimple( real_2d_array& inva, ae_int_t n, ae_int_t updrow, ae_int_t updcolumn, double 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 *************************************************************************/ void alglib::rmatrixinvupdateuv( real_2d_array& inva, ae_int_t n, real_1d_array u, real_1d_array v);
jacobianelliptic
subpackage
132 of 430
10/25/2011 03:12 PM
Functions
jacobianellipticfunc tions
Examples
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. arithmetic IEEE IEEE IEEE IEEE Absolute error (* = relative error): function # trials peak phi 10000 9.2e-16* sn 50000 4.1e-15 cn 40000 3.6e-15 dn 10000 1.3e-12 rms 1.4e-16* 4.6e-16 4.4e-16 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 *************************************************************************/ void alglib::jacobianellipticfunctions( double u, double m, double& sn, double& cn, double& dn, double& ph);
jarquebera
subpackage
133 of 430
10/25/2011 03:12 PM
Functions
jarqueberatest
Examples
jarqueberatest
function
/************************************************************************* Jarque-Bera test This test checks hypotheses about the fact that a sample of normal random variable. given sample X is a
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: BothTails LeftTail RightTail p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected.
Accuracy of the approximation used (5<=N<=1951): p-value [1, 0.1] [0.1, 0.01] [0.01, 0.001] [0.001, 0] relative error (5<=N<=1951) < 1% < 2% < 6% wasn't measured different
For N>1951 accuracy wasn't measured but it shouldn't be sharply from table values.
-- ALGLIB -Copyright 09.04.2007 by Bochkanov Sergey *************************************************************************/ void alglib::jarqueberatest(real_1d_array x, ae_int_t n, double& p);
kmeans
Functions
subpackage
kmeansgenerate
Examples
134 of 430
10/25/2011 03:12 PM
kmeansgenerate
function
/************************************************************************* k-means++ clusterization INPUT PARAMETERS: XY NPoints NVars K Restarts OUTPUT PARAMETERS: Info dataset, array [0..NPoints-1,0..NVars-1]. dataset size, NPoints>=K number of variables, NVars>=1 desired number of clusters, K>=1 number of restarts, Restarts>=1 return code: * -3, if task is degenerate (number of distinct points is less than K) * -1, if incorrect NPoints/NFeatures/K/Restarts was passed * 1, if subroutine finished successfully array[0..NVars-1,0..K-1].matrix whose columns store cluster's centers array[NPoints], which contains cluster indexes
C XYC
-- ALGLIB -Copyright 21.03.2009 by Bochkanov Sergey *************************************************************************/ void alglib::kmeansgenerate( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t k, ae_int_t restarts, ae_int_t& info, real_2d_array& c, integer_1d_array& xyc);
laguerre
Functions
subpackage
laguerrecalculate laguerrecoefficients laguerresum
Examples
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 *************************************************************************/
135 of 430
10/25/2011 03:12 PM
double alglib::laguerrecalculate(ae_int_t n, double 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 *************************************************************************/ void alglib::laguerrecoefficients(ae_int_t n, real_1d_array& c);
laguerresum
function
/************************************************************************* Summation of Laguerre polynomials using Clenshaws 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 *************************************************************************/ double alglib::laguerresum(real_1d_array c, ae_int_t n, double x);
lda
subpackage
Functions
fisherlda fisherldan
Examples
fisherlda
function
/************************************************************************* Multiclass Fisher LDA Subroutine finds coefficients of linear combination which optimally separates training set on classes. 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.
136 of 430
10/25/2011 03:12 PM
NPoints NVars NClasses training set size, NPoints>=0 number of independent variables, NVars>=1 number of classes, NClasses>=2
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. linear combination coefficients, array[0..NVars-1]
-- ALGLIB -Copyright 31.05.2008 by Bochkanov Sergey *************************************************************************/ void alglib::fisherlda( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t nclasses, ae_int_t& info, real_1d_array& w);
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). 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. training set size, NPoints>=0 number of independent variables, NVars>=1 number of classes, NClasses>=2
NPoints NVars NClasses
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. basis, array[0..NVars-1,0..NVars-1] columns of matrix stores basis vectors, sorted by quality of training set separation (in descending order)
137 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 31.05.2008 by Bochkanov Sergey *************************************************************************/ void alglib::fisherldan( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t nclasses, ae_int_t& info, real_2d_array& w);
legendre
Functions
subpackage
legendrecalculate legendrecoefficients legendresum
Examples
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 *************************************************************************/ double alglib::legendrecalculate(ae_int_t n, double 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 *************************************************************************/ void alglib::legendrecoefficients(ae_int_t n, real_1d_array& c);
legendresum
function
/************************************************************************* Summation of Legendre polynomials using Clenshaws recurrence formula. This routine calculates
138 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ double alglib::legendresum(real_1d_array c, ae_int_t n, double x);
linreg
Classes
linearmodel lrreport
subpackage
Functions
lravgerror lravgrelerror lrbuild lrbuilds lrbuildz lrbuildzs lrpack lrprocess lrrmserror lrunpack
Examples
linearmodel
class
/************************************************************************* *************************************************************************/ class linearmodel { };
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.
139 of 430
10/25/2011 03:12 PM
* CVAvgError * CVAvgRelError cross-validation estimate of average error 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 { real_2d_array c; double rmserror; double avgerror; double avgrelerror; double cvrmserror; double cvavgerror; double cvavgrelerror; ae_int_t ncvdefects; integer_1d_array cvdefects; };
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 *************************************************************************/ double alglib::lravgerror( linearmodel lm, real_2d_array xy, ae_int_t 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 *************************************************************************/ double alglib::lravgrelerror( linearmodel lm, real_2d_array xy, ae_int_t npoints);
140 of 430
10/25/2011 03:12 PM
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 NPoints NVars training set, array [0..NPoints-1,0..NVars]: * NVars columns - independent variables * last column - dependent variable training set size, NPoints>NVars+1 number of independent variables 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 linear model in the ALGLIB format. Use subroutines of this unit to work with the model. additional results
LM AR
-- ALGLIB -Copyright 02.08.2008 by Bochkanov Sergey *************************************************************************/ void alglib::lrbuild( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t& info, linearmodel& lm, lrreport& ar);
lrbuilds
function
/************************************************************************* Linear regression Variant of LRBuild which uses vector of standatd deviations (errors in function values). INPUT PARAMETERS: XY S training set, array [0..NPoints-1,0..NVars]: * NVars columns - independent variables * last column - dependent variable standard deviations (errors in function values)
141 of 430
10/25/2011 03:12 PM
array[0..NPoints-1], S[i]>0. training set size, NPoints>NVars+1 number of independent variables 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 linear model in the ALGLIB format. Use subroutines of this unit to work with the model. additional results
NPoints NVars
LM AR
-- ALGLIB -Copyright 02.08.2008 by Bochkanov Sergey *************************************************************************/ void alglib::lrbuilds( real_2d_array xy, real_1d_array s, ae_int_t npoints, ae_int_t nvars, ae_int_t& info, linearmodel& lm, lrreport& ar);
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 *************************************************************************/ void alglib::lrbuildz( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t& info, linearmodel& lm, lrreport& ar);
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 *************************************************************************/
142 of 430
10/25/2011 03:12 PM
void alglib::lrbuildzs( real_2d_array xy, real_1d_array s, ae_int_t npoints, ae_int_t nvars, ae_int_t& info, linearmodel& lm, lrreport& ar);
lrpack
function
/************************************************************************* "Packs" coefficients and creates linear model in ALGLIB format (LRUnpack reversed). INPUT PARAMETERS: V NVars OUTPUT PAREMETERS: LM coefficients, array[0..NVars] number of independent variables linear model.
-- ALGLIB -Copyright 30.08.2008 by Bochkanov Sergey *************************************************************************/ void alglib::lrpack(real_1d_array v, ae_int_t nvars, linearmodel& lm);
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 *************************************************************************/ double alglib::lrprocess(linearmodel lm, real_1d_array 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 --
143 of 430
10/25/2011 03:12 PM
Copyright 30.08.2008 by Bochkanov Sergey *************************************************************************/ double alglib::lrrmserror( linearmodel lm, real_2d_array xy, ae_int_t npoints);
lrunpack
function
/************************************************************************* Unpacks coefficients of linear model. INPUT PARAMETERS: LM OUTPUT PARAMETERS: V NVars linear model in ALGLIB format coefficients, array[0..NVars] constant term (intercept) is stored in the V[NVars]. number of independent variables (one less than number of coefficients)
-- ALGLIB -Copyright 30.08.2008 by Bochkanov Sergey *************************************************************************/ void alglib::lrunpack(linearmodel lm, real_1d_array& v, ae_int_t& nvars);
logit
Classes
logitmodel mnlreport
subpackage
Functions
mnlavgce mnlavgerror mnlavgrelerror mnlclserror mnlpack mnlprocess mnlprocessi mnlrelclserror mnlrmserror mnltrainh mnlunpack
Examples
logitmodel
class
/************************************************************************* *************************************************************************/ class logitmodel
144 of 430
10/25/2011 03:12 PM
{ };
mnlreport
class
/************************************************************************* MNLReport structure contains information about training process: * NGrad number of gradient calculations * NHess number of Hessian calculations *************************************************************************/ class mnlreport { ae_int_t ngrad; ae_int_t nhess; };
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 *************************************************************************/ double alglib::mnlavgce( logitmodel lm, real_2d_array xy, ae_int_t 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 *************************************************************************/ double alglib::mnlavgerror( logitmodel lm, real_2d_array xy, ae_int_t npoints);
145 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ double alglib::mnlavgrelerror( logitmodel lm, real_2d_array xy, ae_int_t ssize);
mnlclserror
function
/************************************************************************* Classification error on test set = MNLRelClsError*NPoints -- ALGLIB -Copyright 10.09.2008 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::mnlclserror( logitmodel lm, real_2d_array xy, ae_int_t npoints);
mnlpack
function
/************************************************************************* "Packs" coefficients and creates logit model in ALGLIB format (MNLUnpack reversed). INPUT PARAMETERS: A NVars NClasses OUTPUT PARAMETERS: LM model (see MNLUnpack) number of independent variables number of classes logit model.
-- ALGLIB -Copyright 10.09.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mnlpack( real_2d_array a, ae_int_t nvars, ae_int_t nclasses, logitmodel& lm);
146 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mnlprocess(logitmodel lm, real_1d_array x, real_1d_array& 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 *************************************************************************/ void alglib::mnlprocessi( logitmodel lm, real_1d_array x, real_1d_array& y);
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 *************************************************************************/ double alglib::mnlrelclserror(
147 of 430
10/25/2011 03:12 PM
logitmodel lm, real_2d_array xy, ae_int_t 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 *************************************************************************/ double alglib::mnlrmserror( logitmodel lm, real_2d_array xy, ae_int_t 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. training set size, NPoints>=1 number of independent variables, NVars>=1 number of classes, NClasses>=2 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 model built training report
NPoints NVars NClasses
LM Rep
-- ALGLIB -Copyright 10.09.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mnltrainh( real_2d_array xy, ae_int_t npoints, ae_int_t nvars, ae_int_t nclasses, ae_int_t& info, logitmodel& lm,
148 of 430
10/25/2011 03:12 PM
mnlreport& rep);
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 OUTPUT PARAMETERS: V NVars NClasses logit model in ALGLIB format coefficients, array[0..NClasses-2,0..NVars] number of independent variables number of classes
-- ALGLIB -Copyright 10.09.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mnlunpack( logitmodel lm, real_2d_array& a, ae_int_t& nvars, ae_int_t& nclasses);
lsfit
Classes
subpackage
barycentricfitreport lsfitreport lsfitstate polynomialfitreport spline1dfitreport
Functions
barycentricfitfloaterhormann barycentricfitfloaterhormannwc lsfitcreatef lsfitcreatefg lsfitcreatefgh lsfitcreatewf lsfitcreatewfg lsfitcreatewfgh lsfitfit lsfitlinear lsfitlinearc lsfitlinearw lsfitlinearwc lsfitresults lsfitsetbc lsfitsetcond lsfitsetscale
149 of 430
10/25/2011 03:12 PM
lsfitsetstpmax lsfitsetxrep polynomialfit polynomialfitwc spline1dfitcubic spline1dfitcubicwc spline1dfithermite spline1dfithermitewc spline1dfitpenalized spline1dfitpenalizedw
Examples
lsfit_d_lin lsfit_d_linc lsfit_d_nlf lsfit_d_nlfb lsfit_d_nlfg lsfit_d_nlfgh lsfit_d_nlscale lsfit_d_pol lsfit_d_polc lsfit_d_spline Unc onstrained (general) linear least squares fitting with and without weights Constrained (general) linear least squares fitting with and without weights Nonlinear fitting using func tion value only Bound c ontstrained nonlinear fitting using func tion value only Nonlinear fitting using gradient Nonlinear fitting using gradient and Hessian Nonlinear fitting with c ustom sc aling and bound c onstraints Unc onstrained polynomial fitting Constrained polynomial fitting Unc onstrained fitting by penalized regression spline
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 { double taskrcond; ae_int_t dbest; double rmserror; double avgerror; double avgrelerror; double maxerror; };
lsfitreport
class
/************************************************************************* Least squares fitting report: TaskRCond reciprocal of task's condition number IterationsCount number of internal iterations RMSError AvgError AvgRelError MaxError RMS error average error average relative error (for non-zero Y[I]) maximum error
WRMSError weighted RMS error *************************************************************************/
150 of 430
10/25/2011 03:12 PM
class lsfitreport { double ae_int_t double double double double double };
taskrcond; iterationscount; rmserror; avgerror; avgrelerror; maxerror; wrmserror;
lsfitstate
class
/************************************************************************* Nonlinear fitter. You should use ALGLIB functions to work with fitter. Never try to access its fields directly! *************************************************************************/ class lsfitstate { };
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 { double taskrcond; double rmserror; double avgerror; double avgrelerror; double maxerror; };
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 { double taskrcond;
151 of 430
10/25/2011 03:12 PM
double double double double }; rmserror; avgerror; avgrelerror; maxerror;
barycentricfitfloaterhormann
function
/************************************************************************* Rational least squares fitting using Floater-Hormann rational functions with optimal D chosen from [0,9]. Equidistant grid with M node functions. Different values of square error) is chosen. Task is used. Complexity of this dominated by the least squares on [min(x),max(x)] is used to build basis D are tried, optimal D (least root mean is linear, so linear least squares solver computational scheme is O(N*M^2) (mostly solver).
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: Infosame 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 *************************************************************************/ void alglib::barycentricfitfloaterhormann( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t m, ae_int_t& info, barycentricinterpolant& b, barycentricfitreport& rep);
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
152 of 430
10/25/2011 03:12 PM
functions. Different values of mean square error) is chosen. solver is used. Complexity (mostly dominated by the least D are tried, optimal D (least WEIGHTED root Task is linear, so linear least squares of this computational scheme is O(N*M^2) squares solver).
SEE ALSO * BarycentricFitFloaterHormann(), "lightweight" fitting without invididual weights and constraints. 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: Infosame 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
153 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::barycentricfitfloaterhormannwc( real_1d_array x, real_1d_array y, real_1d_array w, ae_int_t n, real_1d_array xc, real_1d_array yc, integer_1d_array dc, ae_int_t k, ae_int_t m, ae_int_t& info, barycentricinterpolant& b, barycentricfitreport& rep);
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 M K w x c is is is is is is a number of points, a dimension of a space points belong to, a dimension of a space of parameters being fitted, an N-dimensional vector of weight coefficients, a set of N points, each of them is an M-dimensional vector, 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 DiffStepnumerical 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
154 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 18.10.2008 by Bochkanov Sergey *************************************************************************/ void alglib::lsfitcreatef( real_2d_array x, real_1d_array y, real_1d_array c, double diffstep, lsfitstate& state); void alglib::lsfitcreatef( real_2d_array x, real_1d_array y, real_1d_array c, ae_int_t n, ae_int_t m, ae_int_t k, double diffstep, lsfitstate& state); 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 M K x c is is is is is a a a a a number of points, dimension of a space points belong to, dimension of a space of parameters being fitted, set of N points, each of them is an M-dimensional vector, 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 *************************************************************************/
155 of 430
10/25/2011 03:12 PM
void alglib::lsfitcreatefg( real_2d_array x, real_1d_array y, real_1d_array c, bool cheapfg, lsfitstate& state); void alglib::lsfitcreatefg( real_2d_array x, real_1d_array y, real_1d_array c, ae_int_t n, ae_int_t m, ae_int_t k, bool cheapfg, lsfitstate& state); 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 M K x c is is is is is a a a a a number of points, dimension of a space points belong to, dimension of a space of parameters being fitted, set of N points, each of them is an M-dimensional vector, 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 *************************************************************************/ void alglib::lsfitcreatefgh( real_2d_array x, real_1d_array y, real_1d_array c, lsfitstate& state); void alglib::lsfitcreatefgh( real_2d_array x, real_1d_array y, real_1d_array c, ae_int_t n, ae_int_t m,
156 of 430
10/25/2011 03:12 PM
ae_int_t k, lsfitstate& state); 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 M K w x c is is is is is is a number of points, a dimension of a space points belong to, a dimension of a space of parameters being fitted, an N-dimensional vector of weight coefficients, a set of N points, each of them is an M-dimensional vector, 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 DiffStepnumerical 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 *************************************************************************/ void alglib::lsfitcreatewf( real_2d_array x, real_1d_array y, real_1d_array w, real_1d_array c, double diffstep, lsfitstate& state); void alglib::lsfitcreatewf( real_2d_array x, real_1d_array y, real_1d_array w, real_1d_array c, ae_int_t n, ae_int_t m, ae_int_t k, double diffstep, lsfitstate& state);
157 of 430
10/25/2011 03:12 PM
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 M K w x c is is is is is is a number of points, a dimension of a space points belong to, a dimension of a space of parameters being fitted, an N-dimensional vector of weight coefficients, a set of N points, each of them is an M-dimensional vector, 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 *************************************************************************/ void alglib::lsfitcreatewfg( real_2d_array x, real_1d_array y, real_1d_array w, real_1d_array c, bool cheapfg, lsfitstate& state); void alglib::lsfitcreatewfg( real_2d_array x, real_1d_array y, real_1d_array w, real_1d_array c,
158 of 430
10/25/2011 03:12 PM
ae_int_t n, ae_int_t m, ae_int_t k, bool cheapfg, lsfitstate& state); 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 M K w x c is is is is is is a number of points, a dimension of a space points belong to, a dimension of a space of parameters being fitted, an N-dimensional vector of weight coefficients, a set of N points, each of them is an M-dimensional vector, 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 *************************************************************************/ void alglib::lsfitcreatewfgh( real_2d_array x, real_1d_array y, real_1d_array w, real_1d_array c, lsfitstate& state); void alglib::lsfitcreatewfgh( real_2d_array x, real_1d_array y, real_1d_array w, real_1d_array c, ae_int_t n, ae_int_t m, ae_int_t k, lsfitstate& state); Examples: [1]
lsfitfit
function
10/25/2011 03:12 PM
159 of 430
/************************************************************************* 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, x will be argument, and {c0,c1} will be parameters. then
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 function, which accept different sets of callbacks. versions of this
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 *************************************************************************/ void lsfitfit(lsfitstate &state, void (*func)(const real_1d_array &c, const real_1d_array &x, double &func, void (*rep)(const real_1d_array &c, double func, void *ptr) = NULL, void *ptr = NULL); void lsfitfit(lsfitstate &state, void (*func)(const real_1d_array &c, const real_1d_array &x, double &func, void (*grad)(const real_1d_array &c, const real_1d_array &x, double &func, void (*rep)(const real_1d_array &c, double func, void *ptr) = NULL, void *ptr = NULL); void lsfitfit(lsfitstate &state, void (*func)(const real_1d_array &c, const real_1d_array &x, double &func, void (*grad)(const real_1d_array &c, const real_1d_array &x, double &func,
void *ptr),
void *ptr), real_1d_array &grad, void *ptr
void *ptr), real_1d_array &grad, void *ptr
160 of 430
10/25/2011 03:12 PM
void (*hess)(const real_1d_array &c, const real_1d_array &x, double &func, real_1d_array &grad, real_2d_a void (*rep)(const real_1d_array &c, double func, void *ptr) = NULL, void *ptr = NULL); Examples: [1] [2] [3] [4] [5]
lsfitlinear
function
/************************************************************************* Linear least squares fitting. QR decomposition is used to reduce task to MxM, then triangular solver SVD-based solver is used depending on condition number of the system. allows to maximize speed and retain decent accuracy. or It
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 * 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 -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::lsfitlinear( real_1d_array y, real_2d_array fmatrix, ae_int_t& info, real_1d_array& c, lsfitreport& rep); void alglib::lsfitlinear( real_1d_array y, real_2d_array fmatrix, ae_int_t n, ae_int_t m, ae_int_t& info, real_1d_array& c, lsfitreport& rep); Examples: [1]
lsfitlinearc
function
/************************************************************************* Constained linear least squares fitting.
161 of 430
10/25/2011 03:12 PM
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. 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: * 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. -- ALGLIB -Copyright 07.09.2009 by Bochkanov Sergey *************************************************************************/ void alglib::lsfitlinearc( real_1d_array y, real_2d_array fmatrix, real_2d_array cmatrix, ae_int_t& info, real_1d_array& c, lsfitreport& rep); void alglib::lsfitlinearc( real_1d_array y, real_2d_array fmatrix, real_2d_array cmatrix, ae_int_t n, ae_int_t m, ae_int_t k, ae_int_t& info, real_1d_array& c, lsfitreport& rep); Examples: [1]
lsfitlinearw
function
162 of 430
10/25/2011 03:12 PM
/************************************************************************* Weighted linear least squares fitting. QR decomposition is used to reduce task to MxM, then triangular solver SVD-based solver is used depending on condition number of the system. allows to maximize speed and retain decent accuracy. or It
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 * 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 -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::lsfitlinearw( real_1d_array y, real_1d_array w, real_2d_array fmatrix, ae_int_t& info, real_1d_array& c, lsfitreport& rep); void alglib::lsfitlinearw( real_1d_array y, real_1d_array w, real_2d_array fmatrix, ae_int_t n, ae_int_t m, ae_int_t& info, real_1d_array& c, lsfitreport& rep); Examples: [1]
lsfitlinearwc
function
/************************************************************************* Weighted constained linear least squares fitting. This that is variation K additional of LSFitLinearW(), which searchs for min|A*x=b| given constaints C*x=bc are satisfied. It reduces original
163 of 430
10/25/2011 03:12 PM
task to modified one: min|B*y-d| WITHOUT constraints, is called. then LSFitLinearW()
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: * 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. -- ALGLIB -Copyright 07.09.2009 by Bochkanov Sergey *************************************************************************/ void alglib::lsfitlinearwc( real_1d_array y, real_1d_array w, real_2d_array fmatrix, real_2d_array cmatrix, ae_int_t& info, real_1d_array& c, lsfitreport& rep); void alglib::lsfitlinearwc( real_1d_array y, real_1d_array w, real_2d_array fmatrix, real_2d_array cmatrix, ae_int_t n, ae_int_t m, ae_int_t k, ae_int_t& info, real_1d_array& c, lsfitreport& rep); Examples: [1]
164 of 430
10/25/2011 03:12 PM
lsfitresults
function
/************************************************************************* Nonlinear least squares fitting results. Called after return from LSFitFit(). INPUT PARAMETERS: State algorithm state OUTPUT PARAMETERS: Info completetion code: * 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 C array[0..K-1], solution Rep optimization report. Following fields are set: * Rep.TerminationType completetion code: * 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). -- ALGLIB -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::lsfitresults( lsfitstate state, ae_int_t& info, real_1d_array& c, lsfitreport& rep); 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
165 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::lsfitsetbc( lsfitstate state, real_1d_array bndl, real_1d_array bndu);
lsfitsetcond
function
/************************************************************************* Stopping conditions for nonlinear least squares fitting. INPUT PARAMETERS: State structure which stores algorithm state EpsF stopping criterion. Algorithm stops if |F(k+1)-F(k)| <= EpsF*max{|F(k)|, |F(k+1)|, 1} 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 EpsF=0, 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 *************************************************************************/ void alglib::lsfitsetcond( lsfitstate state, double epsf, double epsx, ae_int_t maxits); Examples: [1] [2] [3] [4] [5]
lsfitsetscale
function
/************************************************************************* This function sets scaling coefficients for underlying optimizer. ALGLIB optimizers use scaling matrices to test stopping conditions (step
166 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::lsfitsetscale(lsfitstate state, real_1d_array 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, want to limit step length.
if you don't
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 *************************************************************************/ void alglib::lsfitsetstpmax(lsfitstate state, double stpmax);
lsfitsetxrep
function
/************************************************************************* This function turns on/off reporting. INPUT PARAMETERS: State structure which stores algorithm state NeedXRepwhether iteration reports are needed or not
167 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::lsfitsetxrep(lsfitstate state, bool needxrep);
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() 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: Infosame 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 *************************************************************************/ void alglib::polynomialfit( real_1d_array x, real_1d_array y, ae_int_t m, ae_int_t& info, barycentricinterpolant& p, polynomialfitreport& rep); void alglib::polynomialfit( real_1d_array x,
168 of 430
10/25/2011 03:12 PM
real_1d_array y, ae_int_t n, ae_int_t m, ae_int_t& info, barycentricinterpolant& p, polynomialfitreport& rep); 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() 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: Infosame 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:
169 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::polynomialfitwc( real_1d_array x, real_1d_array y, real_1d_array w, real_1d_array xc, real_1d_array yc, integer_1d_array dc, ae_int_t m, ae_int_t& info, barycentricinterpolant& p, polynomialfitreport& rep); void alglib::polynomialfitwc( real_1d_array x, real_1d_array y, real_1d_array w, ae_int_t n, real_1d_array xc, real_1d_array yc, integer_1d_array dc, ae_int_t k, ae_int_t m, ae_int_t& info, barycentricinterpolant& p, polynomialfitreport& rep); Examples: [1]
spline1dfitcubic
function
/************************************************************************* Least squares fitting by cubic spline. This subroutine is "lightweight" alternative for more complex and featurerich Spline1DFitCubicWC(). See Spline1DFitCubicWC() for more information
170 of 430
10/25/2011 03:12 PM
about subroutine parameters (we don't duplicate it here because of length) -- ALGLIB PROJECT -Copyright 18.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dfitcubic( real_1d_array x, real_1d_array y, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep); void alglib::spline1dfitcubic( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep);
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() Spline1DFitCubic() fitting by Hermite splines (more flexible, less smooth) "lightweight" fitting by cubic splines, without invididual weights and constraints
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):
171 of 430
10/25/2011 03:12 PM
* 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 number of basis functions ( = number_of_nodes+2), M>=4.
OUTPUT PARAMETERS: Infosame 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 *************************************************************************/ void alglib::spline1dfitcubicwc( real_1d_array x, real_1d_array y, real_1d_array w, real_1d_array xc,
172 of 430
10/25/2011 03:12 PM
real_1d_array yc, integer_1d_array dc, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep); void alglib::spline1dfitcubicwc( real_1d_array x, real_1d_array y, real_1d_array w, ae_int_t n, real_1d_array xc, real_1d_array yc, integer_1d_array dc, ae_int_t k, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep);
spline1dfithermite
function
/************************************************************************* Least squares fitting by Hermite spline. This subroutine is "lightweight" alternative for more complex and featurerich Spline1DFitHermiteWC(). See Spline1DFitHermiteWC() description for more information about subroutine parameters (we don't duplicate it here because of length). -- ALGLIB PROJECT -Copyright 18.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dfithermite( real_1d_array x, real_1d_array y, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep); void alglib::spline1dfithermite( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep);
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
173 of 430
10/25/2011 03:12 PM
computational scheme is O(N*M^2), mostly dominated by least squares solver SEE ALSO Spline1DFitCubicWC() Spline1DFitHermite() fitting by Cubic splines (less flexible, more smooth) "lightweight" Hermite fitting, without invididual weights and constraints
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: Infosame 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.
174 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::spline1dfithermitewc( real_1d_array x, real_1d_array y, real_1d_array w, real_1d_array xc, real_1d_array yc, integer_1d_array dc, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep); void alglib::spline1dfithermitewc( real_1d_array x, real_1d_array y, real_1d_array w, ae_int_t n, real_1d_array xc, real_1d_array yc, integer_1d_array dc, ae_int_t k, ae_int_t m, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep);
spline1dfitpenalized
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
175 of 430
10/25/2011 03:12 PM
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). 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: Infosame 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 *************************************************************************/ void alglib::spline1dfitpenalized( real_1d_array x, real_1d_array y, ae_int_t m, double rho, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep); void alglib::spline1dfitpenalized( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t m, double rho, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep); 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
176 of 430
10/25/2011 03:12 PM
P rho C = C*10^rho*integral{ S''(x)^2*dx } - non-linearity penalty - tunable constant given by user - automatically determined scale parameter, makes penalty invariant with respect to scaling of X, Y, W.
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: Infosame 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, array. so caller may pass unsorted
-- ALGLIB PROJECT -Copyright 19.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dfitpenalizedw( real_1d_array x, real_1d_array y, real_1d_array w, ae_int_t m, double rho, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep);
177 of 430
10/25/2011 03:12 PM
void alglib::spline1dfitpenalizedw( real_1d_array x, real_1d_array y, real_1d_array w, ae_int_t n, ae_int_t m, double rho, ae_int_t& info, spline1dinterpolant& s, spline1dfitreport& rep); Examples: [1]
lsfit_d_lin example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "interpolation.h"
using namespace alglib;
int main(int argc, char **argv) { // // 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). // real_2d_array fmatrix = "[[0.606531],[0.670320],[0.740818],[0.818731],[0.904837],[1.000000],[1.105171],[1 real_1d_array y = "[1.133719, 1.306522, 1.504604, 1.554663, 1.884638, 2.072436, 2.257285, 2.534068, 2.622 ae_int_t info; real_1d_array c; lsfitreport rep; // // Linear fitting without weights // lsfitlinear(y, fmatrix, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", c.tostring(4).c_str()); // EXPECTED: [1.98650] // // Linear fitting with individual weights. // Slightly different result is returned. // real_1d_array w = "[1.414213, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1]"; lsfitlinearw(y, w, fmatrix, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", c.tostring(4).c_str()); // EXPECTED: [1.983354] return 0; }
lsfit_d_linc example
178 of 430 10/25/2011 03:12 PM
using namespace alglib; int main(int argc, char **argv) { // // 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" // real_1d_array y = "[0.072436,0.246944,0.491263,0.522300,0.714064,0.921929]"; real_2d_array fmatrix = "[[1,0.0],[1,0.2],[1,0.4],[1,0.6],[1,0.8],[1,1.0]]"; real_2d_array cmatrix = "[[1,0,0]]"; ae_int_t info; real_1d_array c; lsfitreport rep; // // Constrained fitting without weights // lsfitlinearc(y, fmatrix, cmatrix, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", c.tostring(3).c_str()); // EXPECTED: [0,0.932933] // // Constrained fitting with individual weights // real_1d_array w = "[1, 1.414213, 1, 1, 1, 1]"; lsfitlinearwc(y, w, fmatrix, cmatrix, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", c.tostring(3).c_str()); // EXPECTED: [0,0.938322] return 0; }
lsfit_d_nlf example
#include "stdafx.h" #include <stdlib.h> #include <stdio.h>
179 of 430
10/25/2011 03:12 PM
#include <math.h> #include "interpolation.h" using namespace alglib; void function_cx_1_func(const real_1d_array &c, const real_1d_array &x, double &func, void *ptr) { // this callback calculates f(c,x)=exp(-c0*sqr(x0)) // where x is a position on X-axis and c is adjustable parameter func = exp(-c[0]*pow(x[0],2)); }
int main(int argc, char **argv) { // // 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). // real_2d_array x = "[[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]"; real_1d_array y = "[0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582 real_1d_array c = "[0.3]"; double epsf = 0; double epsx = 0.000001; ae_int_t maxits = 0; ae_int_t info; lsfitstate state; lsfitreport rep; double diffstep = 0.0001; // // Fitting without weights // lsfitcreatef(x, y, c, diffstep, state); lsfitsetcond(state, epsf, epsx, maxits); alglib::lsfitfit(state, function_cx_1_func); lsfitresults(state, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 2 printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [1.5] // // Fitting with weights // (you can change weights and see how it changes result) // real_1d_array w = "[1,1,1,1,1,1,1,1,1,1,1]"; lsfitcreatewf(x, y, w, c, diffstep, state); lsfitsetcond(state, epsf, epsx, maxits); alglib::lsfitfit(state, function_cx_1_func); lsfitresults(state, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 2 printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [1.5] return 0; }
lsfit_d_nlfb example
#include "stdafx.h" #include <stdlib.h>
180 of 430
10/25/2011 03:12 PM
#include <stdio.h> #include <math.h> #include "interpolation.h" using namespace alglib; void function_cx_1_func(const real_1d_array &c, const real_1d_array &x, double &func, void *ptr) { // this callback calculates f(c,x)=exp(-c0*sqr(x0)) // where x is a position on X-axis and c is adjustable parameter func = exp(-c[0]*pow(x[0],2)); }
int main(int argc, char **argv) { // // 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). // real_2d_array x = "[[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]"; real_1d_array y = "[0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582 real_1d_array c = "[0.3]"; real_1d_array bndl = "[0.0]"; real_1d_array bndu = "[1.0]"; double epsf = 0; double epsx = 0.000001; ae_int_t maxits = 0; ae_int_t info; lsfitstate state; lsfitreport rep; double diffstep = 0.0001; lsfitcreatef(x, y, c, diffstep, state); lsfitsetbc(state, bndl, bndu); lsfitsetcond(state, epsf, epsx, maxits); alglib::lsfitfit(state, function_cx_1_func); lsfitresults(state, info, c, rep); printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [1.0] return 0; }
lsfit_d_nlfg example
using namespace alglib; void function_cx_1_func(const real_1d_array &c, const real_1d_array &x, double &func, void *ptr) {
181 of 430
10/25/2011 03:12 PM
// this callback calculates f(c,x)=exp(-c0*sqr(x0)) // where x is a position on X-axis and c is adjustable parameter func = exp(-c[0]*pow(x[0],2));
} void function_cx_1_grad(const real_1d_array &c, const real_1d_array &x, double &func, real_1d_array &grad, vo { // 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 = exp(-c[0]*pow(x[0],2)); grad[0] = -pow(x[0],2)*func; }
int main(int argc, char **argv) { // // In this example we demonstrate exponential fitting // by f(x) = exp(-c*x^2) // using function value and gradient (with respect to c). // real_2d_array x = "[[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]"; real_1d_array y = "[0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582 real_1d_array c = "[0.3]"; double epsf = 0; double epsx = 0.000001; ae_int_t maxits = 0; ae_int_t info; lsfitstate state; lsfitreport rep; // // Fitting without weights // lsfitcreatefg(x, y, c, true, state); lsfitsetcond(state, epsf, epsx, maxits); alglib::lsfitfit(state, function_cx_1_func, function_cx_1_grad); lsfitresults(state, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 2 printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [1.5] // // Fitting with weights // (you can change weights and see how it changes result) // real_1d_array w = "[1,1,1,1,1,1,1,1,1,1,1]"; lsfitcreatewfg(x, y, w, c, true, state); lsfitsetcond(state, epsf, epsx, maxits); alglib::lsfitfit(state, function_cx_1_func, function_cx_1_grad); lsfitresults(state, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 2 printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [1.5] return 0; }
lsfit_d_nlfgh example
182 of 430
10/25/2011 03:12 PM
using namespace alglib; void function_cx_1_func(const real_1d_array &c, const real_1d_array &x, double &func, void *ptr) { // this callback calculates f(c,x)=exp(-c0*sqr(x0)) // where x is a position on X-axis and c is adjustable parameter func = exp(-c[0]*pow(x[0],2)); } void function_cx_1_grad(const real_1d_array &c, const real_1d_array &x, double &func, real_1d_array &grad, vo { // 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 = exp(-c[0]*pow(x[0],2)); grad[0] = -pow(x[0],2)*func; } void function_cx_1_hess(const real_1d_array &c, const real_1d_array &x, double &func, real_1d_array &grad, re { // 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 = exp(-c[0]*pow(x[0],2)); grad[0] = -pow(x[0],2)*func; hess[0][0] = pow(x[0],4)*func; }
int main(int argc, char **argv) { // // In this example we demonstrate exponential fitting // by f(x) = exp(-c*x^2) // using function value, gradient and Hessian (with respect to c) // real_2d_array x = "[[-1],[-0.8],[-0.6],[-0.4],[-0.2],[0],[0.2],[0.4],[0.6],[0.8],[1.0]]"; real_1d_array y = "[0.223130, 0.382893, 0.582748, 0.786628, 0.941765, 1.000000, 0.941765, 0.786628, 0.582 real_1d_array c = "[0.3]"; double epsf = 0; double epsx = 0.000001; ae_int_t maxits = 0; ae_int_t info; lsfitstate state; lsfitreport rep; // // Fitting without weights // lsfitcreatefgh(x, y, c, state); lsfitsetcond(state, epsf, epsx, maxits); alglib::lsfitfit(state, function_cx_1_func, function_cx_1_grad, function_cx_1_hess); lsfitresults(state, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 2 printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [1.5] // // Fitting with weights // (you can change weights and see how it changes result) // real_1d_array w = "[1,1,1,1,1,1,1,1,1,1,1]"; lsfitcreatewfgh(x, y, w, c, state); lsfitsetcond(state, epsf, epsx, maxits); alglib::lsfitfit(state, function_cx_1_func, function_cx_1_grad, function_cx_1_hess); lsfitresults(state, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 2 printf("%s\n", c.tostring(1).c_str()); // EXPECTED: [1.5] return 0;
183 of 430
10/25/2011 03:12 PM
}
lsfit_d_nlscale example
using namespace alglib; void function_debt_func(const real_1d_array &c, const real_1d_array &x, double &func, void *ptr) { // // this callback calculates f(c,x)=c[0]*(1+c[1]*(pow(x[0]-1999,c[2])-1)) // func = c[0]*(1+c[1]*(pow(x[0]-1999,c[2])-1)); } int main(int argc, char **argv) { // // 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. // real_2d_array x = "[[2000],[2001],[2002],[2003],[2004],[2005],[2006],[2007],[2008]]"; real_1d_array y = "[4323239600000.0, 4560913100000.0, 5564091500000.0, 6743189300000.0, 7284064600000.0, real_1d_array c = "[1.0e+13, 1, 1]"; double epsf = 0; double epsx = 1.0e-5; real_1d_array bndl = "[-inf, -10, 0.1]"; real_1d_array bndu = "[+inf, +10, 2.0]"; real_1d_array s = "[1.0e+12, 1, 1]"; ae_int_t maxits = 0; ae_int_t info; lsfitstate state; lsfitreport rep; double diffstep = 1.0e-5;
184 of 430
10/25/2011 03:12 PM
lsfitcreatef(x, y, c, diffstep, state); lsfitsetcond(state, epsf, epsx, maxits); lsfitsetbc(state, bndl, bndu); lsfitsetscale(state, s); alglib::lsfitfit(state, function_debt_func); lsfitresults(state, info, c, rep); printf("%d\n", int(info)); // EXPECTED: 2 printf("%s\n", c.tostring(-2).c_str()); // EXPECTED: [4.142560E+12, 0.434240, 0.565376] return 0; }
lsfit_d_pol example
using namespace alglib; int main(int argc, char **argv) { // // 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. // real_1d_array x = "[0.0,0.1,0.2,0.3,0.4,0.5,0.6,0.7,0.8,0.9,1.0]"; real_1d_array y = "[0.00,0.05,0.26,0.32,0.33,0.43,0.60,0.60,0.77,0.98,1.02]"; ae_int_t m = 2; double t = 2; ae_int_t info; barycentricinterpolant p; polynomialfitreport rep; double v; // // 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). // polynomialfit(x, y, m, info, p, rep); v = barycentriccalc(p, t);
185 of 430
10/25/2011 03:12 PM
printf("%.2f\n", double(v)); // EXPECTED: 2.011 // // Fitting with individual weights // // NOTE: slightly different result is returned // real_1d_array w = "[1,1.414213562,1,1,1,1,1,1,1,1,1]"; real_1d_array xc = "[]"; real_1d_array yc = "[]"; integer_1d_array dc = "[]"; polynomialfitwc(x, y, w, xc, yc, dc, m, info, p, rep); v = barycentriccalc(p, t); printf("%.2f\n", double(v)); // EXPECTED: 2.023 return 0; }
lsfit_d_polc example
using namespace alglib; int main(int argc, char **argv) { // // 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) // real_1d_array x = "[1.0,1.0]"; real_1d_array y = "[0.9,1.1]"; real_1d_array w = "[1,1]"; real_1d_array xc = "[0]"; real_1d_array yc = "[0]"; integer_1d_array dc = "[0]"; double t = 2; ae_int_t m = 2; ae_int_t info; barycentricinterpolant p; polynomialfitreport rep;
186 of 430
10/25/2011 03:12 PM
double v; polynomialfitwc(x, y, w, xc, yc, dc, m, info, p, rep); v = barycentriccalc(p, t); printf("%.2f\n", double(v)); // EXPECTED: 2.000 return 0; }
lsfit_d_spline example
using namespace alglib; int main(int argc, char **argv) { // // 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 // real_1d_array x = "[0.00,0.10,0.20,0.30,0.40,0.50,0.60,0.70,0.80,0.90]"; real_1d_array y = "[0.10,0.00,0.30,0.40,0.30,0.40,0.62,0.68,0.75,0.95]"; ae_int_t info; double v; spline1dinterpolant s; spline1dfitreport rep; double rho; // // 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; spline1dfitpenalized(x, y, 50, rho, info, s, rep); printf("%d\n", int(info)); // EXPECTED: 1 v = spline1dcalc(s, 0.0); printf("%.1f\n", double(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; spline1dfitpenalized(x, y, 50, rho, info, s, rep); printf("%d\n", int(info)); // EXPECTED: 1 v = spline1dcalc(s, 1.0); printf("%.2f\n", double(v)); // EXPECTED: 0.969
187 of 430
10/25/2011 03:12 PM
// // 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; spline1dfitpenalized(x, y, 50, rho, info, s, rep); printf("%d\n", int(info)); // EXPECTED: 1 return 0; }
mannwhitneyu
Functions
mannwhitneyutest
subpackage
Examples
mannwhitneyutest
function
/************************************************************************* Mann-Whitney U-test This test checks hypotheses about whether X and Y are samples continuous distributions of the same shape and same median or 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 is greater than or equal to the median of the second sample) * right-tailed test (null hypothesis - the median of the first is less than or equal to the median of the second sample). of two whether
sample sample
Requirements: * the samples are independent * X and Y are continuous distributions (or discrete distributions wellapproximating 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 LeftTail p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test.
188 of 430
10/25/2011 03:12 PM
If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected.
RightTail
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 5..10 5..10 10..15 10..15 15..100 M N..10 N..100 N..15 N..100 N..100 Max.err. 1.4e-02 2.2e-02 1.0e-02 1.0e-02 6.1e-03 Rms.err. 6.0e-04 5.3e-06 3.2e-04 2.2e-05 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]. -- ALGLIB -Copyright 09.04.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mannwhitneyutest( real_1d_array x, ae_int_t n, real_1d_array y, ae_int_t m, double& bothtails, double& lefttail, double& righttail);
matdet
Functions
subpackage
cmatrixdet cmatrixludet rmatrixdet rmatrixludet spdmatrixcholeskydet spdmatrixdet
Examples
matdet_d_1 matdet_d_2 matdet_d_3 matdet_d_4 matdet_d_5 Determinant Determinant Determinant Determinant Determinant c alc ulation, c alc ulation, c alc ulation, c alc ulation, c alc ulation, real matrix, short form real matrix, full form c omplex matrix, short form c omplex matrix, full form c omplex matrix with zero imaginary part, short form
cmatrixdet
function
/*************************************************************************
189 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ alglib::complex alglib::cmatrixdet(complex_2d_array a); alglib::complex alglib::cmatrixdet(complex_2d_array a, ae_int_t n); 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 *************************************************************************/ alglib::complex alglib::cmatrixludet( complex_2d_array a, integer_1d_array pivots); alglib::complex alglib::cmatrixludet( complex_2d_array a, integer_1d_array pivots, ae_int_t n);
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.
190 of 430
10/25/2011 03:12 PM
* if not given, automatically determined from matrix size (A must be square matrix) Result: determinant of matrix A. -- ALGLIB -Copyright 2005 by Bochkanov Sergey *************************************************************************/ double alglib::rmatrixdet(real_2d_array a); double alglib::rmatrixdet(real_2d_array a, ae_int_t n); 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 *************************************************************************/ double alglib::rmatrixludet(real_2d_array a, integer_1d_array pivots); double alglib::rmatrixludet( real_2d_array a, integer_1d_array pivots, ae_int_t n);
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, its not necessary to specify which triangle - lower or upper - the matrix is stored in. Result:
191 of 430
10/25/2011 03:12 PM
matrix determinant. -- ALGLIB -Copyright 2005-2008 by Bochkanov Sergey *************************************************************************/ double alglib::spdmatrixcholeskydet(real_2d_array a); double alglib::spdmatrixcholeskydet(real_2d_array a, ae_int_t n);
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 isnt used/changed by function * if False, symmetric matrix A is given by its lower triangle, and the upper triangle isnt 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 *************************************************************************/ double alglib::spdmatrixdet(real_2d_array a); double alglib::spdmatrixdet(real_2d_array a, ae_int_t n, bool isupper);
matdet_d_1 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "linalg.h"
using namespace alglib; int main(int argc, char **argv) { real_2d_array b = "[[1,2],[2,1]]"; double a; a = rmatrixdet(b); printf("%.3f\n", double(a)); // EXPECTED: -3 return 0; }
192 of 430
10/25/2011 03:12 PM
matdet_d_2 example
using namespace alglib; int main(int argc, char **argv) { real_2d_array b = "[[5,4],[4,5]]"; double a; a = rmatrixdet(b, 2); printf("%.3f\n", double(a)); // EXPECTED: 9 return 0; }
matdet_d_3 example
using namespace alglib; int main(int argc, char **argv) { complex_2d_array b = "[[1+1i,2],[2,1-1i]]"; alglib::complex a; a = cmatrixdet(b); printf("%s\n", a.tostring(3).c_str()); // EXPECTED: -2 return 0; }
matdet_d_4 example
using namespace alglib; int main(int argc, char **argv) { alglib::complex a; complex_2d_array b = "[[5i,4],[4i,5]]";
193 of 430
10/25/2011 03:12 PM
a = cmatrixdet(b, 2); printf("%s\n", a.tostring(3).c_str()); // EXPECTED: 9i return 0; }
matdet_d_5 example
using namespace alglib; int main(int argc, char **argv) { alglib::complex a; complex_2d_array b = "[[9,1],[2,1]]"; a = cmatrixdet(b); printf("%s\n", a.tostring(3).c_str()); // EXPECTED: 7 return 0; }
matgen
Functions
subpackage
cmatrixrndcond cmatrixrndorthogonal cmatrixrndorthogonalfromtheleft cmatrixrndorthogonalfromtheright hmatrixrndcond hmatrixrndmultiply hpdmatrixrndcond rmatrixrndcond rmatrixrndorthogonal rmatrixrndorthogonalfromtheleft rmatrixrndorthogonalfromtheright smatrixrndcond smatrixrndmultiply spdmatrixrndcond
Examples
cmatrixrndcond
function
/************************************************************************* Generation of random NxN complex matrix with given condition number C and norm2(A)=1 INPUT PARAMETERS:
194 of 430
10/25/2011 03:12 PM
N C matrix size 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 *************************************************************************/ void alglib::cmatrixrndcond(ae_int_t n, double c, complex_2d_array& a);
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] -- ALGLIB routine -04.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixrndorthogonal(ae_int_t n, complex_2d_array& a);
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, Nmatrix size OUTPUT PARAMETERS: A Q*A, where Q is random MxM orthogonal matrix -- ALGLIB routine -04.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixrndorthogonalfromtheleft( complex_2d_array& a, ae_int_t m, ae_int_t n);
cmatrixrndorthogonalfromtheright
function
/************************************************************************* Multiplication of MxN complex matrix by NxN random Haar distributed complex orthogonal matrix INPUT PARAMETERS:
195 of 430
10/25/2011 03:12 PM
A M, Nmatrix, array[0..M-1, 0..N-1] matrix size
OUTPUT PARAMETERS: A A*Q, where Q is random NxN orthogonal matrix -- ALGLIB routine -04.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixrndorthogonalfromtheright( complex_2d_array& a, ae_int_t m, ae_int_t 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 *************************************************************************/ void alglib::hmatrixrndcond(ae_int_t n, double c, complex_2d_array& a);
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 *************************************************************************/ void alglib::hmatrixrndmultiply(complex_2d_array& a, ae_int_t n);
hpdmatrixrndcond
function
/************************************************************************* Generation of random NxN Hermitian positive definite matrix with given condition number and norm2(A)=1
196 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::hpdmatrixrndcond(ae_int_t n, double c, complex_2d_array& a);
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 *************************************************************************/ void alglib::rmatrixrndcond(ae_int_t n, double c, real_2d_array& a);
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] -- ALGLIB routine -04.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixrndorthogonal(ae_int_t n, real_2d_array& a);
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, Nmatrix size
197 of 430
10/25/2011 03:12 PM
OUTPUT PARAMETERS: A Q*A, where Q is random MxM orthogonal matrix -- ALGLIB routine -04.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixrndorthogonalfromtheleft( real_2d_array& a, ae_int_t m, ae_int_t 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, Nmatrix size OUTPUT PARAMETERS: A A*Q, where Q is random NxN orthogonal matrix -- ALGLIB routine -04.12.2009 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixrndorthogonalfromtheright( real_2d_array& a, ae_int_t m, ae_int_t 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 *************************************************************************/ void alglib::smatrixrndcond(ae_int_t n, double c, real_2d_array& a);
smatrixrndmultiply
function
/************************************************************************* Symmetric multiplication of NxN matrix by random Haar distributed orthogonal matrix
198 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::smatrixrndmultiply(real_2d_array& a, ae_int_t 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 *************************************************************************/ void alglib::spdmatrixrndcond(ae_int_t n, double c, real_2d_array& a);
matinv
Classes
matinvreport
subpackage
Functions
cmatrixinverse cmatrixluinverse cmatrixtrinverse hpdmatrixcholeskyinverse hpdmatrixinverse rmatrixinverse rmatrixluinverse rmatrixtrinverse spdmatrixcholeskyinverse spdmatrixinverse
Examples
matinv_d_c1 matinv_d_hpd1 matinv_d_r1 Complex matrix inverse HPD matrix inverse Real matrix inverse
199 of 430
10/25/2011 03:12 PM
matinv_d_spd1 SPD matrix inverse
matinvreport
class
/************************************************************************* Matrix inverse report: * R1 reciprocal of condition number in 1-norm * RInf reciprocal of condition number in inf-norm *************************************************************************/ class matinvreport { double r1; double rinf; };
cmatrixinverse
function
/************************************************************************* Inversion of a general matrix. 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 *************************************************************************/ void alglib::cmatrixinverse( complex_2d_array& a, ae_int_t& info, matinvreport& rep); void alglib::cmatrixinverse( complex_2d_array& a, ae_int_t n, ae_int_t& info, matinvreport& rep); Examples: [1]
cmatrixluinverse
function
/************************************************************************* Inversion of a matrix given by its LU decomposition. 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) :
200 of 430
10/25/2011 03:12 PM
* 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 *************************************************************************/ void alglib::cmatrixluinverse( complex_2d_array& a, integer_1d_array pivots, ae_int_t& info, matinvreport& rep); void alglib::cmatrixluinverse( complex_2d_array& a, integer_1d_array pivots, ae_int_t n, ae_int_t& info, matinvreport& rep);
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 diagonal, and the diagonal elements are not passed to the algorithm. unit
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.
201 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 05.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::cmatrixtrinverse( complex_2d_array& a, bool isupper, ae_int_t& info, matinvreport& rep); void alglib::cmatrixtrinverse( complex_2d_array& a, ae_int_t n, bool isupper, bool isunit, ae_int_t& info, matinvreport& rep);
hpdmatrixcholeskyinverse
function
/************************************************************************* Inversion of a Hermitian positive definite matrix which is given by Cholesky decomposition. 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 isnt used/changed by function * if False, symmetric matrix A is given by its lower triangle, and the upper triangle isnt 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 *************************************************************************/ void alglib::hpdmatrixcholeskyinverse( complex_2d_array& a, ae_int_t& info, matinvreport& rep); void alglib::hpdmatrixcholeskyinverse( complex_2d_array& a, ae_int_t n, bool isupper, ae_int_t& info, matinvreport& rep);
202 of 430
10/25/2011 03:12 PM
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. 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 isnt used/changed by function * if False, symmetric matrix A is given by its lower triangle, and the upper triangle isnt 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 *************************************************************************/ void alglib::hpdmatrixinverse( complex_2d_array& a, ae_int_t& info, matinvreport& rep); void alglib::hpdmatrixinverse( complex_2d_array& a, ae_int_t n, bool isupper, ae_int_t& info, matinvreport& rep); Examples: [1]
rmatrixinverse
function
/************************************************************************* Inversion of a general matrix. 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)
203 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::rmatrixinverse( real_2d_array& a, ae_int_t& info, matinvreport& rep); void alglib::rmatrixinverse( real_2d_array& a, ae_int_t n, ae_int_t& info, matinvreport& rep); Examples: [1]
rmatrixluinverse
function
/************************************************************************* Inversion of a matrix given by its LU decomposition. 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 *************************************************************************/ void alglib::rmatrixluinverse(
204 of 430
10/25/2011 03:12 PM
real_2d_array& a, integer_1d_array pivots, ae_int_t& info, matinvreport& rep); void alglib::rmatrixluinverse( real_2d_array& a, integer_1d_array pivots, ae_int_t n, ae_int_t& info, matinvreport& rep);
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 diagonal, and the diagonal elements are not passed to the algorithm. unit
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 *************************************************************************/ void alglib::rmatrixtrinverse( real_2d_array& a, bool isupper, ae_int_t& info, matinvreport& rep); void alglib::rmatrixtrinverse( real_2d_array& a, ae_int_t n, bool isupper, bool isunit, ae_int_t& info,
205 of 430
10/25/2011 03:12 PM
matinvreport& rep);
spdmatrixcholeskyinverse
function
/************************************************************************* Inversion of a symmetric positive definite matrix which is given by Cholesky decomposition. 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 isnt used/changed by function * if False, symmetric matrix A is given by its lower triangle, and the upper triangle isnt 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 *************************************************************************/ void alglib::spdmatrixcholeskyinverse( real_2d_array& a, ae_int_t& info, matinvreport& rep); void alglib::spdmatrixcholeskyinverse( real_2d_array& a, ae_int_t n, bool isupper, ae_int_t& info, matinvreport& rep);
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. 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
206 of 430
10/25/2011 03:12 PM
overwritten. other elements are unchanged. * if not given, size is automatically determined from matrix size (A must be square matrix) storage type (optional): * if True, symmetric matrix A is given by its upper triangle, and the lower triangle isnt used/changed by function * if False, symmetric matrix A is given by its lower triangle, and the upper triangle isnt used/changed by function * if not given, both lower and upper triangles must be filled.
IsUpper -
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 *************************************************************************/ void alglib::spdmatrixinverse( real_2d_array& a, ae_int_t& info, matinvreport& rep); void alglib::spdmatrixinverse( real_2d_array& a, ae_int_t n, bool isupper, ae_int_t& info, matinvreport& rep); Examples: [1]
matinv_d_c1 example
using namespace alglib; int main(int argc, char **argv) { complex_2d_array a = "[[1i,-1],[1i,1]]"; ae_int_t info; matinvreport rep; cmatrixinverse(a, info, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", a.tostring(4).c_str()); // EXPECTED: [[-0.5i,-0.5i],[-0.5,0.5]] printf("%.4f\n", double(rep.r1)); // EXPECTED: 0.5 printf("%.4f\n", double(rep.rinf)); // EXPECTED: 0.5 return 0; }
207 of 430
10/25/2011 03:12 PM
matinv_d_hpd1 example
using namespace alglib; int main(int argc, char **argv) { complex_2d_array a = "[[2,1],[1,2]]"; ae_int_t info; matinvreport rep; hpdmatrixinverse(a, info, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", a.tostring(4).c_str()); // EXPECTED: [[0.666666,-0.333333],[-0.333333,0.666666]] return 0; }
matinv_d_r1 example
using namespace alglib; int main(int argc, char **argv) { real_2d_array a = "[[1,-1],[1,1]]"; ae_int_t info; matinvreport rep; rmatrixinverse(a, info, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", a.tostring(4).c_str()); // EXPECTED: [[0.5,0.5],[-0.5,0.5]] printf("%.4f\n", double(rep.r1)); // EXPECTED: 0.5 printf("%.4f\n", double(rep.rinf)); // EXPECTED: 0.5 return 0; }
matinv_d_spd1 example
using namespace alglib;
208 of 430
10/25/2011 03:12 PM
int main(int argc, char **argv) { real_2d_array a = "[[2,1],[1,2]]"; ae_int_t info; matinvreport rep; spdmatrixinverse(a, info, rep); printf("%d\n", int(info)); // EXPECTED: 1 printf("%s\n", a.tostring(4).c_str()); // EXPECTED: [[0.666666,-0.333333],[-0.333333,0.666666]] return 0; }
mcpd
subpackage
Classes
mcpdreport mcpdstate
Functions
mcpdaddbc mcpdaddec mcpdaddtrack mcpdcreate mcpdcreateentry mcpdcreateentryexit mcpdcreateexit mcpdresults mcpdsetbc mcpdsetec mcpdsetlc mcpdsetpredictionweights mcpdsetprior mcpdsettikhonovregularizer mcpdsolve
Examples
mcpd_simple1 mcpd_simple2 Simple unc onstrained MCPD model (no entry/exit states) Simple MCPD model (no entry/exit states) with equality c onstraints
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 --
209 of 430
10/25/2011 03:12 PM
Copyright 23.05.2010 by Bochkanov Sergey *************************************************************************/ class mcpdreport { ae_int_t inneriterationscount; ae_int_t outeriterationscount; ae_int_t nfev; ae_int_t terminationtype; };
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 { };
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)
210 of 430
10/25/2011 03:12 PM
* 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 *************************************************************************/ void alglib::mcpdaddbc( mcpdstate s, ae_int_t i, ae_int_t j, double bndl, double 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 without changing constraints for other elements. You can also use MCPDSetEC() function which allows arbitrary set of equality constraints in one call. you P
to specify
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
211 of 430
10/25/2011 03:12 PM
J C 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 *************************************************************************/ void alglib::mcpdaddec(mcpdstate s, ae_int_t i, ae_int_t j, double c); Examples: [1] column index of element being constrained value (constraint for P[I,J]). Can be either constraint) or finite value from [0,1].
NAN
(no
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 *************************************************************************/ void alglib::mcpdaddtrack(mcpdstate s, real_2d_array xy); void alglib::mcpdaddtrack(mcpdstate s, real_2d_array xy, ae_int_t k); Examples: [1] [2]
mcpdcreate
function
/************************************************************************* DESCRIPTION:
212 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mcpdcreate(ae_int_t n, mcpdstate& s); Examples: [1] [2]
mcpdcreateentry
function
/************************************************************************* DESCRIPTION:
213 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mcpdcreateentry( ae_int_t n, ae_int_t entrystate, mcpdstate& s);
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 for "Entry-Exit-states" model, i.e. model where transition X[i+1] is modelled as X[i+1] = P*X[i] Data) solver from X[i] to
214 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mcpdcreateentryexit( ae_int_t n, ae_int_t entrystate, ae_int_t exitstate, mcpdstate& s);
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
215 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mcpdcreateexit(ae_int_t n, ae_int_t exitstate, mcpdstate& s);
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 *************************************************************************/ void alglib::mcpdresults(mcpdstate s, real_2d_array& p, mcpdreport& rep);
216 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mcpdsetbc( mcpdstate s, real_2d_array bndl, real_2d_array bndu);
mcpdsetec
function
217 of 430
10/25/2011 03:12 PM
/************************************************************************* 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 *************************************************************************/ void alglib::mcpdsetec(mcpdstate s, real_2d_array ec);
mcpdsetlc
function
/************************************************************************* This function is used to set linear equality/inequality constraints on the
218 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mcpdsetlc(mcpdstate s, real_2d_array c, integer_1d_array ct); void alglib::mcpdsetlc( mcpdstate s, real_2d_array c, integer_1d_array ct, ae_int_t k);
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
219 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mcpdsetpredictionweights(mcpdstate s, real_1d_array 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 change r with MCPDSetTikhonovRegularizer() function. can also
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 *************************************************************************/ void alglib::mcpdsetprior(mcpdstate s, real_2d_array 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 prior values with MCPDSetPrior() function. also change
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
220 of 430
10/25/2011 03:12 PM
*************************************************************************/ void alglib::mcpdsettikhonovregularizer(mcpdstate s, double 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 *************************************************************************/ void alglib::mcpdsolve(mcpdstate s); Examples: [1] [2]
mcpd_simple1 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "dataanalysis.h"
using namespace alglib; int main(int argc, char **argv) { // // 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
221 of 430
10/25/2011 03:12 PM
// are "good") and [0.8,0.2] (only 80% of portfolio is in the "good" // state) // mcpdstate s; mcpdreport rep; real_2d_array p; real_2d_array track0 = "[[1.00000,0.00000],[0.95000,0.05000],[0.92750,0.07250],[0.91738,0.08263],[0.91282 real_2d_array track1 = "[[0.80000,0.20000],[0.86000,0.14000],[0.88700,0.11300],[0.89915,0.10085]]"; mcpdcreate(2, s); mcpdaddtrack(s, track0); mcpdaddtrack(s, track1); mcpdsolve(s); mcpdresults(s, p, rep); // // 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. // printf("%s\n", p.tostring(2).c_str()); // EXPECTED: [[0.95,0.50],[0.05,0.50]] return 0; }
mcpd_simple2 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "dataanalysis.h"
using namespace alglib; int main(int argc, char **argv) { // // 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 )
222 of 430
10/25/2011 03:12 PM
// 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) // mcpdstate s; mcpdreport rep; real_2d_array p; real_2d_array track0 = "[[1.000000,0.000000,0.000000],[0.950000,0.050000,0.000000],[0.927500,0.060000,0.0 real_2d_array track1 = "[[0.800000,0.200000,0.000000],[0.860000,0.090000,0.050000],[0.862000,0.065500,0.0 mcpdcreate(3, s); mcpdaddtrack(s, track0); mcpdaddtrack(s, track1); mcpdaddec(s, 0, 2, 0.0); mcpdaddec(s, 1, 2, 0.0); mcpdaddec(s, 2, 2, 1.0); mcpdaddec(s, 2, 0, 0.0); mcpdsolve(s); mcpdresults(s, p, rep); // // 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. // printf("%s\n", p.tostring(2).c_str()); // EXPECTED: [[0.95,0.50,0.00],[0.05,0.25,0.00],[0.00,0.25,1.00]] return 0; }
minbleic
Classes
minbleicreport minbleicstate
subpackage
Functions
minbleiccreate minbleiccreatef minbleicoptimize minbleicrestartfrom
223 of 430
10/25/2011 03:12 PM
minbleicresults minbleicresultsbuf minbleicsetbc minbleicsetinnerc ond minbleicsetlc minbleicsetmaxits minbleicsetouterc ond minbleicsetprecdefault minbleicsetprecdiag minbleicsetprecsc ale minbleicsetscale minbleicsetstpmax minbleicsetxrep
Examples
minbleic_d_1 minbleic_d_2 minbleic_ftrim minbleic_numdiff Nonlinear optimization Nonlinear optimization Nonlinear optimization Nonlinear optimization with bound c onstraints with linear inequality c onstraints by BLEIC, func tion with singularities with bound c onstraints and numeric al differentiation
minbleicreport
class
/************************************************************************* This structure stores optimization report: * InnerIterationsCount number of inner iterations * OuterIterationsCount number of outer iterations * NFEV number of gradient evaluations * TerminationType termination type (see below) TERMINATION CODES TerminationType field contains completion code, which can be: -10 unsupported combination of algorithm settings: 1) StpMax is set to non-zero value, AND 2) non-default preconditioner is used. You can't use both features at the same moment, so you have to choose one of them (and to turn off another one). -3 inconsistent constraints. Feasible point is either nonexistent or too hard to find. Try to restart optimizer with better initial approximation 4 conditions on constraints are fulfilled with error less than or equal to EpsC 5 MaxIts steps was taken 7 stopping conditions are too stringent, further improvement is impossible, X contains best point found so far. 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 {
224 of 430
10/25/2011 03:12 PM
ae_int_t ae_int_t ae_int_t ae_int_t double double double double }; inneriterationscount; outeriterationscount; nfev; terminationtype; debugeqerr; debugfs; debugff; debugdx;
minbleicstate
class
/************************************************************************* This object stores nonlinear optimizer state. You should use functions provided by MinBLEIC subpackage to work with this object *************************************************************************/ class minbleicstate { };
minbleiccreate
function
/************************************************************************* BOUND CONSTRAINED OPTIMIZATION WITH ADDITIONAL LINEAR EQUALITY AND INEQUALITY CONSTRAINTS DESCRIPTION: The subroutine minimizes function combination of: * bound constraints * linear inequality constraints * linear equality constraints F(x) of N arguments subject to any
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 for underlying unconstrained solver with MinBLEICSetInnerCond() call. This function controls accuracy of underlying optimization algorithm. 4. User sets stopping conditions for outer iteration by calling MinBLEICSetOuterCond() function.
225 of 430
10/25/2011 03:12 PM
This function controls handling of boundary and inequality constraints. 5. Additionally, user may set limit on number of internal iterations by MinBLEICSetMaxIts() call. This function allows to prevent algorithm from looping forever. 6. User calls MinBLEICOptimize() function which takes algorithm state and pointer (delegate, etc.) to callback function which calculates F/G. 7. User calls MinBLEICResults() to get solution 8. Optionally user may call MinBLEICRestartFrom() to solve another problem with same N but another starting point. MinBLEICRestartFrom() 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 *************************************************************************/ void alglib::minbleiccreate(real_1d_array x, minbleicstate& state); void alglib::minbleiccreate( ae_int_t n, real_1d_array x, minbleicstate& state); 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]. DiffStepdifferentiation step, >0 OUTPUT PARAMETERS: State structure which stores algorithm state NOTES: 1. algorithm uses 4-point central formula for differentiation.
226 of 430
10/25/2011 03:12 PM
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 smalldimensional problems only, and to implement analytical gradient as soon as possible. -- ALGLIB -Copyright 16.05.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minbleiccreatef( real_1d_array x, double diffstep, minbleicstate& state); void alglib::minbleiccreatef( ae_int_t n, real_1d_array x, double diffstep, minbleicstate& state); 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.
227 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void minbleicoptimize(minbleicstate &state, void (*func)(const real_1d_array &x, double &func, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); void minbleicoptimize(minbleicstate &state, void (*grad)(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); Examples: [1] [2] [3] [4]
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 *************************************************************************/ void alglib::minbleicrestartfrom(minbleicstate state, real_1d_array x);
minbleicresults
function
/************************************************************************* BLEIC results INPUT PARAMETERS: State algorithm state OUTPUT PARAMETERS:
228 of 430
10/25/2011 03:12 PM
X Rep array[0..N-1], solution optimization report. You should check Rep.TerminationType in order to distinguish successful termination from unsuccessful one. More information about fields of this structure can be found in the comments on MinBLEICReport datatype.
-- ALGLIB -Copyright 28.11.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minbleicresults( minbleicstate state, real_1d_array& x, minbleicreport& rep); 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 *************************************************************************/ void alglib::minbleicresultsbuf( minbleicstate state, real_1d_array& x, minbleicreport& 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(). 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 * bound constraints are * function is evaluated even when numerical according to boundary following useful always satisfied only INSIDE area differentiation constraints) properties: exactly specified by bound constraints, is used (algorithm adjusts nodes
229 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 28.11.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minbleicsetbc( minbleicstate state, real_1d_array bndl, real_1d_array bndu); Examples: [1] [2]
minbleicsetinnercond
function
/************************************************************************* This function sets stopping conditions for the underlying nonlinear CG optimizer. It controls overall accuracy of solution. These conditions should be strict enough in order for algorithm to converge. 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 - ste pvector, dx=X(k+1)-X(k) * s - scaling coefficients set by MinBLEICSetScale() Passing EpsG=0, EpsF=0 and EpsX=0 (simultaneously) will lead to automatic stopping criterion selection. These conditions are used to terminate inner iterations. However, you need to tune termination conditions for outer iterations too. -- ALGLIB -Copyright 28.11.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minbleicsetinnercond( minbleicstate state, double epsg, double epsf, double epsx); Examples: [1] [2] [3]
minbleicsetlc
function
/************************************************************************* This function sets linear constraints for BLEIC optimizer.
230 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minbleicsetlc( minbleicstate state, real_2d_array c, integer_1d_array ct); void alglib::minbleicsetlc( minbleicstate state, real_2d_array c, integer_1d_array ct, ae_int_t k); Examples: [1]
minbleicsetmaxits
function
/************************************************************************* This function allows to stop algorithm after specified number of inner iterations. INPUT PARAMETERS: State structure which stores algorithm state MaxIts maximum number of inner iterations. If MaxIts=0, the number of iterations is unlimited. -- ALGLIB -Copyright 28.11.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minbleicsetmaxits(minbleicstate state, ae_int_t maxits);
231 of 430
10/25/2011 03:12 PM
minbleicsetoutercond
function
/************************************************************************* This function sets stopping conditions for outer iteration of BLEIC algo. These conditions control accuracy of constraint handling and amount of infeasibility allowed in the solution. INPUT PARAMETERS: State structure which stores algorithm state EpsX >0, stopping condition on outer iteration step length EpsI >0, stopping condition on infeasibility Both EpsX and EpsI must be non-zero. MEANING OF EpsX EpsX is a stopping condition for outer iterations. Algorithm will stop when solution of the current modified subproblem will be within EpsX (using 2-norm) of the previous solution. MEANING OF EpsI EpsI controls feasibility properties - algorithm won't stop until all inequality constraints will be satisfied with error (distance from current point to the feasible area) at most EpsI. -- ALGLIB -Copyright 28.11.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minbleicsetoutercond( minbleicstate state, double epsx, double epsi); Examples: [1] [2] [3]
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 *************************************************************************/ void alglib::minbleicsetprecdefault(minbleicstate 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],
232 of 430
10/25/2011 03:12 PM
(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 *************************************************************************/ void alglib::minbleicsetprecdiag(minbleicstate state, real_1d_array d);
minbleicsetprecscale
function
/************************************************************************* Modification of the preconditioner: scale-based diagonal preconditioning. This preconditioning diagonal of Hessian, (for example, one and most part of the mode can be useful when you don't have approximate but you know that your variables are badly scaled variable is in [1,10], and another in [1000,100000]), ill-conditioning comes from different scales of vars. preconditioner, with H[i] = 1/(s[i]^2),
In this case simple scale-based 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 *************************************************************************/ void alglib::minbleicsetprecscale(minbleicstate 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 along I-th axis is equal to DiffStep*S[I]. - step
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
233 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minbleicsetscale(minbleicstate state, real_1d_array 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, want to limit step length.
if you don't
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 *************************************************************************/ void alglib::minbleicsetstpmax(minbleicstate state, double stpmax);
minbleicsetxrep
function
/************************************************************************* This function turns on/off reporting. INPUT PARAMETERS: State structure which stores algorithm state NeedXRepwhether iteration reports are needed or not If NeedXRep is True, algorithm will call rep() callback function if provided to MinBLEICOptimize(). it is
-- ALGLIB -Copyright 28.11.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minbleicsetxrep(minbleicstate state, bool needxrep);
234 of 430
10/25/2011 03:12 PM
minbleic_d_1 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "optimization.h"
using namespace alglib; void function1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // and its derivatives df/d0 and df/dx1 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3); } int main(int argc, char **argv) { // // 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. // real_1d_array x = "[0,0]"; real_1d_array bndl = "[-1,-1]"; real_1d_array bndu = "[+1,+1]"; minbleicstate state; minbleicreport rep; // // These variables define stopping conditions for the underlying CG algorithm. // They should be stringent enough in order to guarantee overall stability // of the outer iterations. // // We use very simple condition - |g|<=epsg // double epsg = 0.000001; double epsf = 0; double epsx = 0; // // These variables define stopping conditions for the outer iterations: // * epso controls convergence of outer iterations; algorithm will stop // when difference between solutions of subsequent unconstrained problems // will be less than 0.0001 // * epsi controls amount of infeasibility allowed in the final solution // double epso = 0.00001; double epsi = 0.00001; // // 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... // minbleiccreate(x, state); minbleicsetbc(state, bndl, bndu); minbleicsetinnercond(state, epsg, epsf, epsx); minbleicsetoutercond(state, epso, epsi);
235 of 430
10/25/2011 03:12 PM
alglib::minbleicoptimize(state, function1_grad); minbleicresults(state, x, rep); // // ...and evaluate these results // printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-1,1] return 0; }
minbleic_d_2 example
using namespace alglib; void function1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // and its derivatives df/d0 and df/dx1 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3); } int main(int argc, char **argv) { // // 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. // real_1d_array x = "[5,5]"; real_2d_array c = "[[1,0,2],[1,1,6]]"; integer_1d_array ct = "[1,1]"; minbleicstate state; minbleicreport rep; // // These variables define stopping conditions for the underlying CG algorithm. // They should be stringent enough in order to guarantee overall stability // of the outer iterations. // // We use very simple condition - |g|<=epsg // double epsg = 0.000001; double epsf = 0; double epsx = 0; // // These variables define stopping conditions for the outer iterations: // * epso controls convergence of outer iterations; algorithm will stop // when difference between solutions of subsequent unconstrained problems
236 of 430
10/25/2011 03:12 PM
// will be less than 0.0001 // * epsi controls amount of infeasibility allowed in the final solution // double epso = 0.00001; double epsi = 0.00001; // // 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... // minbleiccreate(x, state); minbleicsetlc(state, c, ct); minbleicsetinnercond(state, epsg, epsf, epsx); minbleicsetoutercond(state, epso, epsi); alglib::minbleicoptimize(state, function1_grad); minbleicresults(state, x, rep); // // ...and evaluate these results // printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [2,4] return 0; }
minbleic_ftrim example
using namespace alglib; void s1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // 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) || (x[0]>=+0.999999999999) ) { func = 1.0E+300; return; } func = pow(1+x[0],-0.2) + pow(1-x[0],-0.3) + 1000*x[0]; grad[0] = -0.2*pow(1+x[0],-1.2) +0.3*pow(1-x[0],-1.3) + 1000; } int main(int argc, char **argv) { // // 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
237 of 430
10/25/2011 03:12 PM
// - without using boundary constraints! // // See http://www.alglib.net/optimization/tipsandtricks.php#ftrimming for more information // on this subject. // real_1d_array x = "[0]"; double epsg = 1.0e-6; double epsf = 0; double epsx = 0; double epso = 1.0e-6; double epsi = 1.0e-6; minbleicstate state; minbleicreport rep; minbleiccreate(x, state); minbleicsetinnercond(state, epsg, epsf, epsx); minbleicsetoutercond(state, epso, epsi); alglib::minbleicoptimize(state, s1_grad); minbleicresults(state, x, rep); printf("%s\n", x.tostring(5).c_str()); // EXPECTED: [-0.99917305] return 0; }
minbleic_numdiff example
using namespace alglib; void function1_func(const real_1d_array &x, double &func, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); } int main(int argc, char **argv) { // // 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. // real_1d_array x = "[0,0]"; real_1d_array bndl = "[-1,-1]"; real_1d_array bndu = "[+1,+1]"; minbleicstate state; minbleicreport rep; // // These variables define stopping conditions for the underlying CG algorithm. // They should be stringent enough in order to guarantee overall stability // of the outer iterations. // // We use very simple condition - |g|<=epsg // double epsg = 0.000001;
238 of 430
10/25/2011 03:12 PM
double epsf = 0; double epsx = 0; // // These variables define stopping conditions for the outer iterations: // * epso controls convergence of outer iterations; algorithm will stop // when difference between solutions of subsequent unconstrained problems // will be less than 0.0001 // * epsi controls amount of infeasibility allowed in the final solution // double epso = 0.00001; double epsi = 0.00001; // // This variable contains differentiation step // double 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... // minbleiccreatef(x, diffstep, state); minbleicsetbc(state, bndl, bndu); minbleicsetinnercond(state, epsg, epsf, epsx); minbleicsetoutercond(state, epso, epsi); alglib::minbleicoptimize(state, function1_func); minbleicresults(state, x, rep); // // ...and evaluate these results // printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-1,1] return 0; }
mincg
Classes
subpackage
mincgreport mincgstate
Functions
mincgcreate mincgcreatef mincgoptimize mincgrestartfrom mincgresults mincgresultsbuf mincgsetcgtype mincgsetcond mincgsetprecdefault mincgsetprecdiag
239 of 430
10/25/2011 03:12 PM
mincgsetprecscale mincgsetscale mincgsetstpmax mincgsetxrep mincgsuggeststep
Examples
mincg_d_1 mincg_d_2 mincg_ftrim mincg_numdiff Nonlinear optimization Nonlinear optimization Nonlinear optimization Nonlinear optimization by CG with additional settings and restarts by CG, func tion with singularities by CG with numeric al differentiation
mincgreport
class
/************************************************************************* *************************************************************************/ class mincgreport { ae_int_t iterationscount; ae_int_t nfev; ae_int_t terminationtype; };
mincgstate
class
/************************************************************************* This object stores state of the nonlinear CG optimizer. You should use ALGLIB functions to work with this object. *************************************************************************/ class mincgstate { };
mincgcreate
function
/************************************************************************* NONLINEAR CONJUGATE GRADIENT METHOD DESCRIPTION: The subroutine minimizes function F(x) of N arguments by using one of nonlinear conjugate gradient methods. the
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
240 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mincgcreate(real_1d_array x, mincgstate& state); void alglib::mincgcreate(ae_int_t n, real_1d_array x, mincgstate& state); 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]. DiffStepdifferentiation 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.
241 of 430
10/25/2011 03:12 PM
Imprecise gradient may slow down convergence, especially on highly nonlinear problems. Thus we recommend to use this function for fast prototyping on smalldimensional problems only, and to implement analytical gradient as soon as possible. -- ALGLIB -Copyright 16.05.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mincgcreatef( real_1d_array x, double diffstep, mincgstate& state); void alglib::mincgcreatef( ae_int_t n, real_1d_array x, double diffstep, mincgstate& state); 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
242 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void mincgoptimize(mincgstate &state, void (*func)(const real_1d_array &x, double &func, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); void mincgoptimize(mincgstate &state, void (*grad)(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); Examples: [1] [2] [3] [4]
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 *************************************************************************/ void alglib::mincgrestartfrom(mincgstate state, real_1d_array 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: * 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
243 of 430
10/25/2011 03:12 PM
* 8 terminated by user * Rep.IterationsCount contains iterations count * NFEV countains number of function calculations -- ALGLIB -Copyright 20.04.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mincgresults( mincgstate state, real_1d_array& x, mincgreport& rep); 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 *************************************************************************/ void alglib::mincgresultsbuf( mincgstate state, real_1d_array& x, mincgreport& 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 *************************************************************************/ void alglib::mincgsetcgtype(mincgstate state, ae_int_t 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
244 of 430
10/25/2011 03:12 PM
|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() >=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. >=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() maximum number of iterations. If MaxIts=0, the number of iterations is unlimited.
EpsF
EpsX
MaxIts
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 *************************************************************************/ void alglib::mincgsetcond( mincgstate state, double epsg, double epsf, double epsx, ae_int_t maxits); Examples: [1] [2] [3]
mincgsetprecdefault
function
/************************************************************************* Modification of the preconditioner: preconditioning is turned off. INPUT PARAMETERS: State structure which stores algorithm state NOTE: you can iterations. change preconditioner "on the fly", during algorithm
-- ALGLIB -Copyright 13.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::mincgsetprecdefault(mincgstate 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).
245 of 430
10/25/2011 03:12 PM
NOTE: you can iterations.
change
preconditioner
"on
the
fly",
during algorithm
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 *************************************************************************/ void alglib::mincgsetprecdiag(mincgstate state, real_1d_array d);
mincgsetprecscale
function
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 iterations. change preconditioner "on the fly", during algorithm
-- ALGLIB -Copyright 13.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::mincgsetprecscale(mincgstate 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 along I-th axis is equal to DiffStep*S[I]. step
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
246 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::mincgsetscale(mincgstate state, real_1d_array s);
mincgsetstpmax
function
if you don't
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 *************************************************************************/ void alglib::mincgsetstpmax(mincgstate state, double stpmax);
mincgsetxrep
function
/************************************************************************* This function turns on/off reporting. INPUT PARAMETERS: State structure which stores algorithm state NeedXRepwhether iteration reports are needed or not If NeedXRep is True, algorithm will call rep() callback function if provided to MinCGOptimize(). it is
-- ALGLIB -Copyright 02.04.2010 by Bochkanov Sergey *************************************************************************/ void alglib::mincgsetxrep(mincgstate state, bool needxrep);
mincgsuggeststep
function
/************************************************************************* This function allows to suggest initial step length to the CG algorithm.
247 of 430
10/25/2011 03:12 PM
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, it is available, to generate initial estimate of step length. if
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 *************************************************************************/ void alglib::mincgsuggeststep(mincgstate state, double stp);
mincg_d_1 example
using namespace alglib; void function1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // and its derivatives df/d0 and df/dx1 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3); } int main(int argc, char **argv) { // // This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4 // with nonlinear conjugate gradient method. // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0;
248 of 430
10/25/2011 03:12 PM
ae_int_t maxits = 0; mincgstate state; mincgreport rep; mincgcreate(x, state); mincgsetcond(state, epsg, epsf, epsx, maxits); alglib::mincgoptimize(state, function1_grad); mincgresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3] return 0; }
mincg_d_2 example
using namespace alglib; void function1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // and its derivatives df/d0 and df/dx1 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3); } int main(int argc, char **argv) { // // 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 // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; double stpmax = 0.1; ae_int_t maxits = 0; mincgstate state; mincgreport rep; // first run mincgcreate(x, state); mincgsetcond(state, epsg, epsf, epsx, maxits); mincgsetstpmax(state, stpmax); alglib::mincgoptimize(state, function1_grad); mincgresults(state, x, rep); printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3]
249 of 430
10/25/2011 03:12 PM
// second run - algorithm is restarted with mincgrestartfrom() x = "[10,10]"; mincgrestartfrom(state, x); alglib::mincgoptimize(state, function1_grad); mincgresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3] return 0; }
mincg_ftrim example
using namespace alglib; void s1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // 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) || (x[0]>=+0.999999999999) ) { func = 1.0E+300; return; } func = pow(1+x[0],-0.2) + pow(1-x[0],-0.3) + 1000*x[0]; grad[0] = -0.2*pow(1+x[0],-1.2) +0.3*pow(1-x[0],-1.3) + 1000; } int main(int argc, char **argv) { // // 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. // real_1d_array x = "[0]"; double epsg = 1.0e-6; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; mincgstate state; mincgreport rep; mincgcreate(x, state); mincgsetcond(state, epsg, epsf, epsx, maxits); alglib::mincgoptimize(state, s1_grad); mincgresults(state, x, rep);
250 of 430
10/25/2011 03:12 PM
printf("%s\n", x.tostring(5).c_str()); // EXPECTED: [-0.99917305] return 0; }
mincg_numdiff example
using namespace alglib; void function1_func(const real_1d_array &x, double &func, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); } int main(int argc, char **argv) { // // This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4 // using numerical differentiation to calculate gradient. // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; double diffstep = 1.0e-6; ae_int_t maxits = 0; mincgstate state; mincgreport rep; mincgcreatef(x, diffstep, state); mincgsetcond(state, epsg, epsf, epsx, maxits); alglib::mincgoptimize(state, function1_func); mincgresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3] return 0; }
mincomp
Classes
minasareport minasastate
subpackage
Functions
minasacreate
251 of 430
10/25/2011 03:12 PM
minasaoptimize minasarestartfrom minasaresults minasaresultsbuf minasasetalgorithm minasasetcond minasasetstpmax minasasetxrep minbleicsetbarrierdec ay minbleicsetbarrierwidth minlbfgssetcholeskyprec onditioner minlbfgssetdefaultprec onditioner
Examples
minasareport
class
/************************************************************************* *************************************************************************/ class minasareport { ae_int_t iterationscount; ae_int_t nfev; ae_int_t terminationtype; ae_int_t activeconstraints; };
minasastate
class
/************************************************************************* *************************************************************************/ class minasastate { };
minasacreate
function
/************************************************************************* Obsolete optimization algorithm. Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 25.03.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minasacreate( real_1d_array x, real_1d_array bndl, real_1d_array bndu, minasastate& state); void alglib::minasacreate( ae_int_t n, real_1d_array x, real_1d_array bndl, real_1d_array bndu, minasastate& state);
252 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void minasaoptimize(minasastate &state, void (*grad)(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL);
minasarestartfrom
function
/************************************************************************* Obsolete optimization algorithm. Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 30.07.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minasarestartfrom( minasastate state, real_1d_array x, real_1d_array bndl, real_1d_array bndu);
minasaresults
function
/************************************************************************* Obsolete optimization algorithm. Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 20.03.2009 by Bochkanov Sergey *************************************************************************/ void alglib::minasaresults( minasastate state, real_1d_array& x, minasareport& rep);
minasaresultsbuf
function
/************************************************************************* Obsolete optimization algorithm.
253 of 430
10/25/2011 03:12 PM
Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 20.03.2009 by Bochkanov Sergey *************************************************************************/ void alglib::minasaresultsbuf( minasastate state, real_1d_array& x, minasareport& rep);
minasasetalgorithm
function
/************************************************************************* Obsolete optimization algorithm. Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 02.04.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minasasetalgorithm(minasastate state, ae_int_t algotype);
minasasetcond
function
/************************************************************************* Obsolete optimization algorithm. Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 02.04.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minasasetcond( minasastate state, double epsg, double epsf, double epsx, ae_int_t maxits);
minasasetstpmax
function
/************************************************************************* Obsolete optimization algorithm. Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 02.04.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minasasetstpmax(minasastate state, double stpmax);
minasasetxrep
function
/************************************************************************* Obsolete optimization algorithm. Was replaced by MinBLEIC subpackage. -- ALGLIB -Copyright 02.04.2010 by Bochkanov Sergey
254 of 430
10/25/2011 03:12 PM
*************************************************************************/ void alglib::minasasetxrep(minasastate state, bool 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 *************************************************************************/ void alglib::minbleicsetbarrierdecay(minbleicstate state, double 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 *************************************************************************/ void alglib::minbleicsetbarrierwidth(minbleicstate state, double mu);
minlbfgssetcholeskypreconditioner
function
/************************************************************************* Obsolete function, use MinLBFGSSetCholeskyPreconditioner() instead. -- ALGLIB -Copyright 13.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgssetcholeskypreconditioner( minlbfgsstate state, real_2d_array p, bool isupper);
minlbfgssetdefaultpreconditioner
function
/************************************************************************* Obsolete function, use MinLBFGSSetPrecDefault() instead. -- ALGLIB -Copyright 13.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgssetdefaultpreconditioner(minlbfgsstate state);
minlbfgs
Classes
subpackage
255 of 430
10/25/2011 03:12 PM
minlbfgsreport minlbfgsstate
Functions
minlbfgscreate minlbfgscreatef minlbfgsoptimize minlbfgsrestartfrom minlbfgsresults minlbfgsresultsbuf minlbfgssetcond minlbfgssetpreccholesky minlbfgssetprecdefault minlbfgssetprecdiag minlbfgssetprecsc ale minlbfgssetscale minlbfgssetstpmax minlbfgssetxrep
Examples
minlbfgs_d_1 minlbfgs_d_2 minlbfgs_ftrim minlbfgs_numdiff Nonlinear optimization Nonlinear optimization Nonlinear optimization Nonlinear optimization by L-BFGS with additional settings and restarts by LBFGS, func tion with singularities by L-BFGS with numeric al differentiation
minlbfgsreport
class
/************************************************************************* *************************************************************************/ class minlbfgsreport { ae_int_t iterationscount; ae_int_t nfev; ae_int_t terminationtype; };
minlbfgsstate
class
/************************************************************************* *************************************************************************/ class minlbfgsstate { };
minlbfgscreate
function
/************************************************************************* LIMITED MEMORY BFGS METHOD FOR LARGE SCALE OPTIMIZATION DESCRIPTION: The subroutine minimizes function F(x) of N arguments by using a Newton method (LBFGS scheme) which is optimized to use a minimum quasiamount
256 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minlbfgscreate( ae_int_t m, real_1d_array x, minlbfgsstate& state); void alglib::minlbfgscreate( ae_int_t n, ae_int_t m, real_1d_array x, minlbfgsstate& state); Examples: [1] [2] [3]
minlbfgscreatef
function
10/25/2011 03:12 PM
257 of 430
/************************************************************************* 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]. DiffStepdifferentiation 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 smalldimensional problems only, and to implement analytical gradient as soon as possible. -- ALGLIB -Copyright 16.05.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgscreatef( ae_int_t m, real_1d_array x, double diffstep, minlbfgsstate& state); void alglib::minlbfgscreatef( ae_int_t n, ae_int_t m, real_1d_array x, double diffstep, minlbfgsstate& state); Examples: [1]
minlbfgsoptimize
function
10/25/2011 03:12 PM
258 of 430
/************************************************************************* 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 *************************************************************************/ void minlbfgsoptimize(minlbfgsstate &state, void (*func)(const real_1d_array &x, double &func, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); void minlbfgsoptimize(minlbfgsstate &state, void (*grad)(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); Examples: [1] [2] [3] [4]
minlbfgsrestartfrom
function
/*************************************************************************
259 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minlbfgsrestartfrom(minlbfgsstate state, real_1d_array 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: * -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 * Rep.IterationsCount contains iterations count * NFEV countains number of function calculations -- ALGLIB -Copyright 02.04.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgsresults( minlbfgsstate state, real_1d_array& x, minlbfgsreport& rep); 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
260 of 430
10/25/2011 03:12 PM
where array reallocation penalty is too large to be ignored. -- ALGLIB -Copyright 20.08.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgsresultsbuf( minlbfgsstate state, real_1d_array& x, minlbfgsreport& 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 *************************************************************************/ void alglib::minlbfgssetcond( minlbfgsstate state, double epsg, double epsf, double epsx, ae_int_t maxits); Examples: [1] [2] [3]
minlbfgssetpreccholesky
function
/************************************************************************* Modification of the preconditioner: Cholesky factorization of approximate Hessian is used. INPUT PARAMETERS:
261 of 430
10/25/2011 03:12 PM
State P structure which stores algorithm state triangular preconditioner, Cholesky factorization of the approximate Hessian. array[0..N-1,0..N-1], (if larger, only leading N elements are used). whether upper or lower triangle of P is given (other triangle is not referenced) (P is copied
IsUpper -
After call to this function preconditioner is changed to P into the internal buffer). NOTE: you can iterations. NOTE 2: P change preconditioner "on the fly",
during algorithm
should
be nonsingular. Exception will be thrown otherwise.
-- ALGLIB -Copyright 13.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgssetpreccholesky( minlbfgsstate state, real_2d_array p, bool 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 iterations. change preconditioner "on the fly", during algorithm
-- ALGLIB -Copyright 13.10.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgssetprecdefault(minlbfgsstate 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 iterations. change preconditioner "on the fly", during algorithm
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
262 of 430
10/25/2011 03:12 PM
*************************************************************************/ void alglib::minlbfgssetprecdiag(minlbfgsstate state, real_1d_array d);
minlbfgssetprecscale
function
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 *************************************************************************/ void alglib::minlbfgssetprecscale(minlbfgsstate 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 along I-th axis is equal to DiffStep*S[I]. - step
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 --
263 of 430
10/25/2011 03:12 PM
Copyright 14.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgssetscale(minlbfgsstate state, real_1d_array 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), you don't want to limit step length.
if
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 *************************************************************************/ void alglib::minlbfgssetstpmax(minlbfgsstate state, double stpmax);
minlbfgssetxrep
function
/************************************************************************* This function turns on/off reporting. INPUT PARAMETERS: State structure which stores algorithm state NeedXRepwhether iteration reports are needed or not If NeedXRep is True, algorithm will call rep() callback function if provided to MinLBFGSOptimize(). it is
-- ALGLIB -Copyright 02.04.2010 by Bochkanov Sergey *************************************************************************/ void alglib::minlbfgssetxrep(minlbfgsstate state, bool needxrep);
minlbfgs_d_1 example
using namespace alglib; void function1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // and its derivatives df/d0 and df/dx1 //
264 of 430
10/25/2011 03:12 PM
func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3); } int main(int argc, char **argv) { // // This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4 // using LBFGS method. // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; minlbfgsstate state; minlbfgsreport rep; minlbfgscreate(1, x, state); minlbfgssetcond(state, epsg, epsf, epsx, maxits); alglib::minlbfgsoptimize(state, function1_grad); minlbfgsresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3] return 0; }
minlbfgs_d_2 example
using namespace alglib; void function1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // and its derivatives df/d0 and df/dx1 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3); } int main(int argc, char **argv) { // // 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 // real_1d_array x = "[0,0]"; double epsg = 0.0000000001;
265 of 430
10/25/2011 03:12 PM
double epsf = 0; double epsx = 0; double stpmax = 0.1; ae_int_t maxits = 0; minlbfgsstate state; minlbfgsreport rep; // first run minlbfgscreate(1, x, state); minlbfgssetcond(state, epsg, epsf, epsx, maxits); minlbfgssetstpmax(state, stpmax); alglib::minlbfgsoptimize(state, function1_grad); minlbfgsresults(state, x, rep); printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3] // second run - algorithm is restarted x = "[10,10]"; minlbfgsrestartfrom(state, x); alglib::minlbfgsoptimize(state, function1_grad); minlbfgsresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3] return 0; }
minlbfgs_ftrim example
using namespace alglib; void s1_grad(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr) { // // 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) || (x[0]>=+0.999999999999) ) { func = 1.0E+300; return; } func = pow(1+x[0],-0.2) + pow(1-x[0],-0.3) + 1000*x[0]; grad[0] = -0.2*pow(1+x[0],-1.2) +0.3*pow(1-x[0],-1.3) + 1000; } int main(int argc, char **argv) { // // 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
266 of 430
10/25/2011 03:12 PM
// on this subject. // real_1d_array x = "[0]"; double epsg = 1.0e-6; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; minlbfgsstate state; minlbfgsreport rep; minlbfgscreate(1, x, state); minlbfgssetcond(state, epsg, epsf, epsx, maxits); alglib::minlbfgsoptimize(state, s1_grad); minlbfgsresults(state, x, rep); printf("%s\n", x.tostring(5).c_str()); // EXPECTED: [-0.99917305] return 0; }
minlbfgs_numdiff example
using namespace alglib; void function1_func(const real_1d_array &x, double &func, void *ptr) { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + (x1-3)^4 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); } int main(int argc, char **argv) { // // This example demonstrates minimization of f(x,y) = 100*(x+3)^4+(y-3)^4 // using numerical differentiation to calculate gradient. // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; double diffstep = 1.0e-6; ae_int_t maxits = 0; minlbfgsstate state; minlbfgsreport rep; minlbfgscreatef(1, x, diffstep, state); minlbfgssetcond(state, epsg, epsf, epsx, maxits); alglib::minlbfgsoptimize(state, function1_func); minlbfgsresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,3] return 0; }
267 of 430
10/25/2011 03:12 PM
minlm
Classes
subpackage
minlmreport minlmstate
Functions
minlmcreatefgh minlmcreatefgj minlmcreatefj minlmcreatev minlmcreatevgj minlmcreatevj minlmoptimize minlmrestartfrom minlmresults minlmresultsbuf minlmsetacctype minlmsetbc minlmsetcond minlmsetscale minlmsetstpmax minlmsetxrep
Examples
minlm_d_fgh minlm_d_restarts minlm_d_v minlm_d_vb minlm_d_vj Nonlinear Hessian-based optimization for general func tions Effic ient restarts of LM optimizer Nonlinear least squares optimization using func tion vec tor only Bound c onstrained nonlinear least squares optimization Nonlinear least squares optimization using func tion vec tor and Jac obian
minlmreport
class
/************************************************************************* Optimization report, filled by MinLMResults() function FIELDS: * TerminationType, completetion code: * -9 derivative correctness check failed; see Rep.WrongNum, Rep.WrongI, Rep.WrongJ for more information. * 1 relative function improvement is no more than EpsF. * 2 relative step is no more than EpsX. * 4 gradient is no more than EpsG. * 5 MaxIts steps was taken * 7 stopping conditions are too stringent, further improvement is impossible * IterationsCount, contains iterations count * NFunc, number of function calculations * NJac, number of Jacobi matrix calculations * NGrad, number of gradient calculations
268 of 430
10/25/2011 03:12 PM
* NHess, number of Hessian calculations * NCholesky, number of Cholesky decomposition calculations *************************************************************************/ class minlmreport { ae_int_t iterationscount; ae_int_t terminationtype; ae_int_t nfunc; ae_int_t njac; ae_int_t ngrad; ae_int_t nhess; ae_int_t ncholesky; };
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 { };
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.
269 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minlmcreatefgh(real_1d_array x, minlmstate& state); void alglib::minlmcreatefgh( ae_int_t n, real_1d_array x, minlmstate& state); 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 *************************************************************************/ void alglib::minlmcreatefgj( ae_int_t m, real_1d_array x, minlmstate& state); void alglib::minlmcreatefgj( ae_int_t n, ae_int_t m, real_1d_array x, minlmstate& state);
minlmcreatefj
function
10/25/2011 03:12 PM
270 of 430
/************************************************************************* 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 *************************************************************************/ void alglib::minlmcreatefj( ae_int_t m, real_1d_array x, minlmstate& state); void alglib::minlmcreatefj( ae_int_t n, ae_int_t m, real_1d_array x, minlmstate& state);
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 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 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 as to
271 of 430
10/25/2011 03:12 PM
* if not given, automatically determined from size of X number of functions f[i] initial solution, array[0..N-1] differentiation step, >0
M X DiffStep-
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 *************************************************************************/ void alglib::minlmcreatev( ae_int_t m, real_1d_array x, double diffstep, minlmstate& state); void alglib::minlmcreatev( ae_int_t n, ae_int_t m, real_1d_array x, double diffstep, minlmstate& state); 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 *************************************************************************/ void alglib::minlmcreatevgj( ae_int_t m, real_1d_array x, minlmstate& state); void alglib::minlmcreatevgj( ae_int_t n, ae_int_t m, real_1d_array x, minlmstate& state);
minlmcreatevj
function
/************************************************************************* IMPROVED LEVENBERG-MARQUARDT METHOD FOR NON-LINEAR LEAST SQUARES OPTIMIZATION DESCRIPTION:
272 of 430
10/25/2011 03:12 PM
This function is used to find minimum of function which is represented 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 *************************************************************************/ void alglib::minlmcreatevj( ae_int_t m, real_1d_array x, minlmstate& state); void alglib::minlmcreatevj( ae_int_t n, ae_int_t m, real_1d_array x, minlmstate& state); as
273 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void minlmoptimize(minlmstate &state, void (*fvec)(const real_1d_array &x, real_1d_array &fi, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); void minlmoptimize(minlmstate &state, void (*fvec)(const real_1d_array &x, real_1d_array &fi, void *ptr), void (*jac)(const real_1d_array &x, real_1d_array &fi, real_2d_array &jac, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); void minlmoptimize(minlmstate &state, void (*func)(const real_1d_array &x, double &func, void *ptr), void (*grad)(const real_1d_array &x, double &func, real_1d_array &grad, void *ptr), void (*hess)(const real_1d_array &x, double &func, real_1d_array &grad, real_2d_array &hess, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL); void minlmoptimize(minlmstate &state, void (*func)(const real_1d_array &x, double &func, void *ptr), void (*jac)(const real_1d_array &x, real_1d_array &fi, real_2d_array &jac, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL,
274 of 430
10/25/2011 03:12 PM
void *ptr = NULL); void minlmoptimize(minlmstate &state, void (*func)(const real_1d_array &x, void (*grad)(const real_1d_array &x, void (*jac)(const real_1d_array &x, void (*rep)(const real_1d_array &x, void *ptr = NULL); Examples: [1] [2] [3] [4] [5]
double &func, void *ptr), double &func, real_1d_array &grad, void *ptr), real_1d_array &fi, real_2d_array &jac, void *ptr), double func, void *ptr) = NULL,
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 *************************************************************************/ void alglib::minlmrestartfrom(minlmstate state, real_1d_array 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; see comments for this structure for more info. -- ALGLIB -Copyright 10.03.2009 by Bochkanov Sergey *************************************************************************/ void alglib::minlmresults( minlmstate state, real_1d_array& x, minlmreport& rep); Examples: [1] [2] [3] [4] [5]
minlmresultsbuf
function
/************************************************************************* Levenberg-Marquardt algorithm results
275 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minlmresultsbuf( minlmstate state, real_1d_array& x, minlmreport& 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 prohibitive 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 V VJ FGH 0 + + + 1 + + comment
DAFAULT VALUES: protocol V VJ FGH 0 x x 1 x comment without acceleration it is so slooooooooow
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 *************************************************************************/ void alglib::minlmsetacctype(minlmstate state, ae_int_t acctype);
276 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minlmsetbc( minlmstate state, real_1d_array bndl, real_1d_array bndu);
minlmsetcond
function
/************************************************************************* This function sets stopping conditions for Levenberg-Marquardt 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 MinLMSetScale() 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 MinLMSetScale()
277 of 430
10/25/2011 03:12 PM
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 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 *************************************************************************/ void alglib::minlmsetcond( minlmstate state, double epsg, double epsf, double epsx, ae_int_t maxits); Examples: [1] [2] [3] [4] [5]
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 *************************************************************************/ void alglib::minlmsetscale(minlmstate state, real_1d_array 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
278 of 430
10/25/2011 03:12 PM
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 *************************************************************************/ void alglib::minlmsetstpmax(minlmstate state, double stpmax);
minlmsetxrep
function
/************************************************************************* This function turns on/off reporting. INPUT PARAMETERS: State structure which stores algorithm state NeedXRepwhether 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 *************************************************************************/ void alglib::minlmsetxrep(minlmstate state, bool needxrep);
minlm_d_fgh example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "optimization.h" void *ptr) (x1-3)^4
using namespace alglib; void function1_func(const real_1d_array &x, double &func, { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); } void function1_grad(const real_1d_array &x, double &func, { // // this callback calculates f(x0,x1) = 100*(x0+3)^4 + // and its derivatives df/d0 and df/dx1 // func = 100*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3);
real_1d_array &grad, void *ptr) (x1-3)^4
279 of 430
10/25/2011 03:12 PM
} void function1_hess(const real_1d_array &x, double &func, real_1d_array &grad, real_2d_array &hess, void *ptr { // // 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*pow(x[0]+3,4) + pow(x[1]-3,4); grad[0] = 400*pow(x[0]+3,3); grad[1] = 4*pow(x[1]-3,3); hess[0][0] = 1200*pow(x[0]+3,2); hess[0][1] = 0; hess[1][0] = 0; hess[1][1] = 12*pow(x[1]-3,2); } int main(int argc, char **argv) { // // 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)} // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; minlmstate state; minlmreport rep; minlmcreatefgh(x, state); minlmsetcond(state, epsg, epsf, epsx, maxits); alglib::minlmoptimize(state, function1_func, function1_grad, function1_hess); minlmresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,+3] return 0; }
minlm_d_restarts example
using namespace alglib; void function1_fvec(const real_1d_array &x, real_1d_array &fi, void *ptr) { //
280 of 430
10/25/2011 03:12 PM
// this callback calculates // f0(x0,x1) = 100*(x0+3)^4, // f1(x0,x1) = (x1-3)^4 // fi[0] = 10*pow(x[0]+3,2); fi[1] = pow(x[1]-3,2); } void { function2_fvec(const real_1d_array &x, real_1d_array &fi, void *ptr) // // 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; } int main(int argc, char **argv) { // // 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. // real_1d_array x; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; minlmstate state; minlmreport rep; // // create optimizer using minlmcreatev() // x = "[10,10]"; minlmcreatev(2, x, 0.0001, state); minlmsetcond(state, epsg, epsf, epsx, maxits); alglib::minlmoptimize(state, function1_fvec); minlmresults(state, x, rep); printf("%s\n", x.tostring(2).c_str()); // 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]"; minlmrestartfrom(state, x); alglib::minlmoptimize(state, function2_fvec); minlmresults(state, x, rep); printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [0,1] return 0; }
minlm_d_v example
281 of 430 10/25/2011 03:12 PM
using namespace alglib; void function1_fvec(const real_1d_array &x, real_1d_array &fi, void *ptr) { // // this callback calculates // f0(x0,x1) = 100*(x0+3)^4, // f1(x0,x1) = (x1-3)^4 // fi[0] = 10*pow(x[0]+3,2); fi[1] = pow(x[1]-3,2); } int main(int argc, char **argv) { // // 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. // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; minlmstate state; minlmreport rep; minlmcreatev(2, x, 0.0001, state); minlmsetcond(state, epsg, epsf, epsx, maxits); alglib::minlmoptimize(state, function1_fvec); minlmresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,+3] return 0; }
minlm_d_vb example
using namespace alglib; void function1_fvec(const real_1d_array &x, real_1d_array &fi, void *ptr)
282 of 430
10/25/2011 03:12 PM
{ // // this callback calculates // f0(x0,x1) = 100*(x0+3)^4, // f1(x0,x1) = (x1-3)^4 // fi[0] = 10*pow(x[0]+3,2); fi[1] = pow(x[1]-3,2); } int main(int argc, char **argv) { // // 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. // real_1d_array x = "[0,0]"; real_1d_array bndl = "[-1,-1]"; real_1d_array bndu = "[+1,+1]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; minlmstate state; minlmreport rep; minlmcreatev(2, x, 0.0001, state); minlmsetbc(state, bndl, bndu); minlmsetcond(state, epsg, epsf, epsx, maxits); alglib::minlmoptimize(state, function1_fvec); minlmresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-1,+1] return 0; }
minlm_d_vj example
using namespace alglib; void function1_fvec(const real_1d_array &x, real_1d_array &fi, void *ptr)
283 of 430
10/25/2011 03:12 PM
{ // // this callback calculates // f0(x0,x1) = 100*(x0+3)^4, // f1(x0,x1) = (x1-3)^4 // fi[0] = 10*pow(x[0]+3,2); fi[1] = pow(x[1]-3,2); } void { function1_jac(const real_1d_array &x, real_1d_array &fi, real_2d_array &jac, void *ptr) // // 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*pow(x[0]+3,2); fi[1] = pow(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); } int main(int argc, char **argv) { // // 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}. // real_1d_array x = "[0,0]"; double epsg = 0.0000000001; double epsf = 0; double epsx = 0; ae_int_t maxits = 0; minlmstate state; minlmreport rep; minlmcreatevj(2, x, state); minlmsetcond(state, epsg, epsf, epsx, maxits); alglib::minlmoptimize(state, function1_fvec, function1_jac); minlmresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [-3,+3] return 0; }
minqp
subpackage
284 of 430
10/25/2011 03:12 PM
Classes
minqpreport minqpstate
Functions
minqpcreate minqpoptimize minqpresults minqpresultsbuf minqpsetalgocholesky minqpsetbc minqpsetlinearterm minqpsetorigin minqpsetquadratic term minqpsetstartingpoint
Examples
minqp_d_bc1 minqp_d_u1 Constrained dense quadratic programming Unc onstrained dense quadratic programming
minqpreport
class
/************************************************************************* This structure stores optimization report: * InnerIterationsCount number of inner iterations * OuterIterationsCount number of outer iterations * NCholesky number of Cholesky decomposition * NMV number of matrix-vector products (only products calculated as part of iterative process are counted) * TerminationType completion code (see below) Completion codes: * -5 inappropriate solver was used: * Cholesky solver for semidefinite or indefinite problems * Cholesky solver for problems with non-boundary constraints * -3 inconsistent constraints (or, maybe, feasible point is too hard to find). If you are sure that constraints are feasible, try to restart optimizer with better initial approximation. * 4 successful completion * 5 MaxIts steps was taken * 7 stopping conditions are too stringent, further improvement is impossible, X contains best point found so far. *************************************************************************/ class minqpreport { ae_int_t inneriterationscount; ae_int_t outeriterationscount; ae_int_t nmv; ae_int_t ncholesky; ae_int_t terminationtype; };
minqpstate
class
10/25/2011 03:12 PM
285 of 430
/************************************************************************* This object stores nonlinear optimizer state. You should use functions provided by MinQP subpackage to work with this object *************************************************************************/ class minqpstate { };
minqpcreate
function
/************************************************************************* CONSTRAINED QUADRATIC PROGRAMMING The subroutine creates QP optimizer. After initial creation, it contains default optimization problem with zero quadratic and linear terms and no constraints. You should set quadratic/linear terms with calls to functions provided by MinQP subpackage. INPUT PARAMETERS: N problem size OUTPUT PARAMETERS: State optimizer with zero quadratic/linear terms and no constraints -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpcreate(ae_int_t n, minqpstate& state); Examples: [1] [2]
minqpoptimize
function
/************************************************************************* This function solves quadratic programming problem. You should call it after setting solver options with MinQPSet...() calls. INPUT PARAMETERS: State algorithm state You should use MinQPResults() function to access results after calls to this function. -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpoptimize(minqpstate state); Examples: [1] [2]
minqpresults
function
/************************************************************************* QP solver results INPUT PARAMETERS:
286 of 430
10/25/2011 03:12 PM
State algorithm state
OUTPUT PARAMETERS: X array[0..N-1], solution Rep optimization report. You should check Rep.TerminationType, which contains completion code, and you may check another fields which contain another information about algorithm functioning. -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpresults( minqpstate state, real_1d_array& x, minqpreport& rep); Examples: [1] [2]
minqpresultsbuf
function
/************************************************************************* QP results Buffered implementation of MinQPResults() 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 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpresultsbuf( minqpstate state, real_1d_array& x, minqpreport& rep);
minqpsetalgocholesky
function
/************************************************************************* This function tells solver to use Cholesky-based algorithm. Cholesky-based algorithm can be used when: * problem is convex * there is no constraints or only boundary constraints are present This algorithm has O(N^3) complexity for unconstrained problem and is up to several times slower on bound constrained problems (these additional iterations are needed to identify active constraints). INPUT PARAMETERS: State structure which stores algorithm state -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpsetalgocholesky(minqpstate state);
287 of 430
10/25/2011 03:12 PM
minqpsetbc
function
/************************************************************************* This function sets boundary constraints for QP solver Boundary constraints are inactive by default (after initial creation). After being set, 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: 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]. -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpsetbc( minqpstate state, real_1d_array bndl, real_1d_array bndu);
minqpsetlinearterm
function
/************************************************************************* This function sets linear term for QP solver. By default, linear term is zero. INPUT PARAMETERS: State structure which stores algorithm state B linear term, array[N]. -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpsetlinearterm(minqpstate state, real_1d_array b); Examples: [1] [2]
minqpsetorigin
function
/************************************************************************* This function sets origin for QP solver. By default, following QP program is solved: min(0.5*x'*A*x+b'*x) This function allows to solve different problem:
288 of 430
10/25/2011 03:12 PM
min(0.5*(x-x_origin)'*A*(x-x_origin)+b'*(x-x_origin)) INPUT PARAMETERS: State structure which stores algorithm state XOrigin origin, array[N]. -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpsetorigin(minqpstate state, real_1d_array xorigin);
minqpsetquadraticterm
function
/************************************************************************* This function sets quadratic term for QP solver. By default quadratic term is zero. IMPORTANT: this solver minimizes following function: f(x) = 0.5*x'*A*x + b'*x. Note that quadratic term has 0.5 before it. So if you want f(x) = x^2 + x you should rewrite your problem as follows: f(x) = 0.5*(2*x^2) + x and your matrix A will be equal to [[2.0]], not to [[1.0]]
to
minimize
INPUT PARAMETERS: State structure which stores algorithm state A matrix, array[N,N] IsUpper (optional) storage type: * if True, symmetric matrix A is given by its upper triangle, and the lower triangle isnt used * if False, symmetric matrix A is given by its lower triangle, and the upper triangle isnt used * if not given, both lower and upper triangles must be filled. -- ALGLIB -Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpsetquadraticterm(minqpstate state, real_2d_array a); void alglib::minqpsetquadraticterm( minqpstate state, real_2d_array a, bool isupper); Examples: [1] [2]
minqpsetstartingpoint
function
/************************************************************************* This function sets starting point for QP solver. It is useful to have good initial approximation to the solution, because it will increase speed of convergence and identification of active constraints. INPUT PARAMETERS: State structure which stores algorithm state X starting point, array[N]. -- ALGLIB --
289 of 430
10/25/2011 03:12 PM
Copyright 11.01.2011 by Bochkanov Sergey *************************************************************************/ void alglib::minqpsetstartingpoint(minqpstate state, real_1d_array x); Examples: [1] [2]
minqp_d_bc1 example
using namespace alglib; int main(int argc, char **argv) { // // This example demonstrates minimization of F(x0,x1) = x0^2 + x1^2 -6*x0 - 4*x1 // subject to bound constraints 0<=x0<=2.5, 0<=x1<=2.5 // // Exact solution is [x0,x1] = [2.5,2] // // We provide algorithm with starting point. With such small problem good starting // point is not really necessary, but with high-dimensional problem it can save us // a lot of time. // // IMPORTANT: this solver minimizes following function: // f(x) = 0.5*x'*A*x + b'*x. // Note that quadratic term has 0.5 before it. So if you want to minimize // quadratic function, you should rewrite it in such way that quadratic term // is multiplied by 0.5 too. // For example, our function is f(x)=x0^2+x1^2+..., but we rewrite it as // f(x) = 0.5*(2*x0^2+2*x1^2) + .... // and pass diag(2,2) as quadratic term - NOT diag(1,1)! // real_2d_array a = "[[2,0],[0,2]]"; real_1d_array b = "[-6,-4]"; real_1d_array x0 = "[0,1]"; real_1d_array bndl = "[0.0,0.0]"; real_1d_array bndu = "[2.5,2.5]"; real_1d_array x; minqpstate state; minqpreport rep; minqpcreate(2, state); minqpsetquadraticterm(state, a); minqpsetlinearterm(state, b); minqpsetstartingpoint(state, x0); minqpsetbc(state, bndl, bndu); minqpoptimize(state); minqpresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [2.5,2] return 0; }
290 of 430
10/25/2011 03:12 PM
minqp_d_u1 example
using namespace alglib; int main(int argc, char **argv) { // // This example demonstrates minimization of F(x0,x1) = x0^2 + x1^2 -6*x0 - 4*x1 // // Exact solution is [x0,x1] = [3,2] // // We provide algorithm with starting point, although in this case // (dense matrix, no constraints) it can work without such information. // // IMPORTANT: this solver minimizes following function: // f(x) = 0.5*x'*A*x + b'*x. // Note that quadratic term has 0.5 before it. So if you want to minimize // quadratic function, you should rewrite it in such way that quadratic term // is multiplied by 0.5 too. // For example, our function is f(x)=x0^2+x1^2+..., but we rewrite it as // f(x) = 0.5*(2*x0^2+2*x1^2) + .... // and pass diag(2,2) as quadratic term - NOT diag(1,1)! // real_2d_array a = "[[2,0],[0,2]]"; real_1d_array b = "[-6,-4]"; real_1d_array x0 = "[0,1]"; real_1d_array x; minqpstate state; minqpreport rep; minqpcreate(2, state); minqpsetquadraticterm(state, a); minqpsetlinearterm(state, b); minqpsetstartingpoint(state, x0); minqpoptimize(state); minqpresults(state, x, rep); printf("%d\n", int(rep.terminationtype)); // EXPECTED: 4 printf("%s\n", x.tostring(2).c_str()); // EXPECTED: [3,2] return 0; }
mlpbase
Classes
subpackage
multilayerperceptron
Functions
mlpactivationfunc tion
291 of 430
10/25/2011 03:12 PM
mlpavgce mlpavgerror mlpavgrelerror mlpclserror mlpcreate0 mlpcreate1 mlpcreate2 mlpcreateb0 mlpcreateb1 mlpcreateb2 mlpcreatec0 mlpcreatec1 mlpcreatec2 mlpcreater0 mlpcreater1 mlpcreater2 mlperror mlperrorn mlpgetinputscaling mlpgetlayerscount mlpgetlayersize mlpgetneuroninfo mlpgetoutputscaling mlpgetweight mlpgrad mlpgradbatch mlpgradn mlpgradnbatch mlphessianbatch mlphessiannbatch mlpissoftmax mlpprocess mlpprocessi mlpproperties mlprandomize mlprandomizefull mlprelclserror mlprmserror mlpserialize mlpsetinputscaling mlpsetneuroninfo mlpsetoutputscaling mlpsetweight mlpunserialize
Examples
multilayerperceptron
class
/************************************************************************* *************************************************************************/ class multilayerperceptron { };
292 of 430
10/25/2011 03:12 PM
mlpactivationfunction
function
/************************************************************************* Neural network activation function INPUT PARAMETERS: NET K OUTPUT PARAMETERS: F DF D2F neuron input function index (zero for linear function) function its derivative its second derivative
-- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpactivationfunction( double net, ae_int_t k, double& f, double& df, double& d2f);
mlpavgce
function
/************************************************************************* Average cross-entropy (in bits per element) on the test set INPUT PARAMETERS: Network neural network XY test set NPoints test set size RESULT: CrossEntropy/(NPoints*LN(2)). Zero if network solves regression task. -- ALGLIB -Copyright 08.01.2009 by Bochkanov Sergey *************************************************************************/ double alglib::mlpavgce( multilayerperceptron network, real_2d_array xy, ae_int_t npoints);
mlpavgerror
function
/************************************************************************* Average error on the test set INPUT PARAMETERS: Network neural network 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
293 of 430
10/25/2011 03:12 PM
probabilities. -- ALGLIB -Copyright 11.03.2008 by Bochkanov Sergey *************************************************************************/ double alglib::mlpavgerror( multilayerperceptron network, real_2d_array xy, ae_int_t npoints);
mlpavgrelerror
function
/************************************************************************* Average relative error on the test set INPUT PARAMETERS: Network neural network 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 11.03.2008 by Bochkanov Sergey *************************************************************************/ double alglib::mlpavgrelerror( multilayerperceptron network, real_2d_array xy, ae_int_t npoints);
mlpclserror
function
/************************************************************************* Classification error -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::mlpclserror( multilayerperceptron network, real_2d_array xy, ae_int_t ssize);
mlpcreate0
function
/************************************************************************* Creates neural network with NIn inputs, NOut outputs, without hidden layers, with linear output layer. Network weights are filled with small random values. -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreate0( ae_int_t nin,
294 of 430
10/25/2011 03:12 PM
ae_int_t nout, multilayerperceptron& network);
mlpcreate1
function
/************************************************************************* Same as MLPCreate0, but with one hidden layer (NHid neurons) with non-linear activation function. Output layer is linear. -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreate1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, multilayerperceptron& network);
mlpcreate2
function
/************************************************************************* Same as MLPCreate0, but with two hidden layers (NHid1 and NHid2 neurons) with non-linear activation function. Output layer is linear. $ALL -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreate2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, multilayerperceptron& network);
mlpcreateb0
function
/************************************************************************* Creates neural network with NIn inputs, NOut outputs, without hidden layers with non-linear output layer. Network weights are filled with small random values. Activation function of the output layer takes values: (B, +INF), if D>=0 or (-INF, B), if D<0. -- ALGLIB -Copyright 30.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreateb0( ae_int_t nin, ae_int_t nout, double b,
295 of 430
10/25/2011 03:12 PM
double d, multilayerperceptron& network);
mlpcreateb1
function
/************************************************************************* Same as MLPCreateB0 but with non-linear hidden layer. -- ALGLIB -Copyright 30.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreateb1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, double b, double d, multilayerperceptron& network);
mlpcreateb2
function
/************************************************************************* Same as MLPCreateB0 but with two non-linear hidden layers. -- ALGLIB -Copyright 30.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreateb2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, double b, double d, multilayerperceptron& network);
mlpcreatec0
function
/************************************************************************* Creates classifier network with NIn inputs and NOut possible classes. Network contains no hidden layers and linear output layer with SOFTMAXnormalization (so outputs sums up to 1.0 and converge to posterior probabilities). -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreatec0( ae_int_t nin, ae_int_t nout, multilayerperceptron& network);
mlpcreatec1
function
/************************************************************************* Same as MLPCreateC0, but with one non-linear hidden layer.
296 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreatec1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, multilayerperceptron& network);
mlpcreatec2
function
/************************************************************************* Same as MLPCreateC0, but with two non-linear hidden layers. -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreatec2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, multilayerperceptron& network);
mlpcreater0
function
/************************************************************************* Creates neural network with NIn inputs, NOut outputs, without hidden layers with non-linear output layer. Network weights are filled with small random values. Activation function of the output layer takes values [A,B]. -- ALGLIB -Copyright 30.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreater0( ae_int_t nin, ae_int_t nout, double a, double b, multilayerperceptron& network);
mlpcreater1
function
/************************************************************************* Same as MLPCreateR0, but with non-linear hidden layer. -- ALGLIB -Copyright 30.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreater1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, double a, double b, multilayerperceptron& network);
297 of 430
10/25/2011 03:12 PM
mlpcreater2
function
/************************************************************************* Same as MLPCreateR0, but with two non-linear hidden layers. -- ALGLIB -Copyright 30.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mlpcreater2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, double a, double b, multilayerperceptron& network);
mlperror
function
/************************************************************************* Error function for neural network, internal subroutine. -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ double alglib::mlperror( multilayerperceptron network, real_2d_array xy, ae_int_t ssize);
mlperrorn
function
/************************************************************************* Natural error function for neural network, internal subroutine. -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ double alglib::mlperrorn( multilayerperceptron network, real_2d_array xy, ae_int_t ssize);
mlpgetinputscaling
function
/************************************************************************* This function returns offset/scaling coefficients for I-th input of the network. INPUT PARAMETERS: Network I OUTPUT PARAMETERS: Mean Sigma network input index mean term sigma term, guaranteed to be nonzero.
298 of 430
10/25/2011 03:12 PM
I-th input is passed through linear transformation IN[i] = (IN[i]-Mean)/Sigma before feeding to the network -- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mlpgetinputscaling( multilayerperceptron network, ae_int_t i, double& mean, double& sigma);
mlpgetlayerscount
function
/************************************************************************* This function returns total number of layers (including input, hidden and output layers). -- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::mlpgetlayerscount(multilayerperceptron network);
mlpgetlayersize
function
/************************************************************************* This function returns size of K-th layer. K=0 corresponds to input layer, K=CNT-1 corresponds to output layer. Size of the output layer is always equal to the number of outputs, although when we have softmax-normalized network, last neuron doesn't have any connections - it is just zero. -- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::mlpgetlayersize( multilayerperceptron network, ae_int_t k);
mlpgetneuroninfo
function
/************************************************************************* This function returns information about Ith neuron of Kth layer INPUT PARAMETERS: Network K I OUTPUT PARAMETERS: FKind Threshold network layer index neuron index (within layer) activation function type (used by MLPActivationFunction()) this value is zero for input or linear neurons also called offset, bias zero for input neurons
299 of 430
10/25/2011 03:12 PM
NOTE: this function throws exception if layer or neuron with do not exists. given index
-- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mlpgetneuroninfo( multilayerperceptron network, ae_int_t k, ae_int_t i, ae_int_t& fkind, double& threshold);
mlpgetoutputscaling
function
/************************************************************************* This function returns offset/scaling coefficients for I-th output of the network. INPUT PARAMETERS: Network I OUTPUT PARAMETERS: Mean Sigma network input index mean term sigma term, guaranteed to be nonzero.
I-th output is passed through linear transformation OUT[i] = OUT[i]*Sigma+Mean before returning it to user. In case we have SOFTMAX-normalized network, we return (Mean,Sigma)=(0.0,1.0). -- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mlpgetoutputscaling( multilayerperceptron network, ae_int_t i, double& mean, double& sigma);
mlpgetweight
function
/************************************************************************* This function returns information about connection from I0-th neuron of K0-th layer to I1-th neuron of K1-th layer. INPUT PARAMETERS: Network K0 I0 K1 I1 network layer index neuron index (within layer) layer index neuron index (within layer)
RESULT: connection weight (zero for non-existent connections) This function: 1. throws exception if layer or neuron with given index do not exists. 2. returns zero if neurons exist, but there is no connection between them
300 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ double alglib::mlpgetweight( multilayerperceptron network, ae_int_t k0, ae_int_t i0, ae_int_t k1, ae_int_t i1);
mlpgrad
function
/************************************************************************* Gradient calculation INPUT PARAMETERS: Network network initialized with one of the network creation funcs X input vector, length of array must be at least NIn DesiredYdesired outputs, length of array must be at least NOut Grad possibly preallocated array. If size of array is smaller than WCount, it will be reallocated. It is recommended to reuse previously allocated array to reduce allocation overhead. OUTPUT PARAMETERS: E error function, SUM(sqr(y[i]-desiredy[i])/2,i) Grad gradient of E with respect to weights of network, array[WCount] -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpgrad( multilayerperceptron network, real_1d_array x, real_1d_array desiredy, double& e, real_1d_array& grad);
mlpgradbatch
function
/************************************************************************* Batch gradient calculation for a set of inputs/outputs INPUT PARAMETERS: Network network initialized with one of the network creation funcs XY set of inputs/outputs; one sample = one row; first NIn columns contain inputs, next NOut columns - desired outputs. SSize number of elements in XY Grad possibly preallocated array. If size of array is smaller than WCount, it will be reallocated. It is recommended to reuse previously allocated array to reduce allocation overhead. OUTPUT PARAMETERS: E error function, SUM(sqr(y[i]-desiredy[i])/2,i) Grad gradient of E with respect to weights of network, array[WCount] -- ALGLIB --
301 of 430
10/25/2011 03:12 PM
Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpgradbatch( multilayerperceptron network, real_2d_array xy, ae_int_t ssize, double& e, real_1d_array& grad);
mlpgradn
function
/************************************************************************* Gradient calculation (natural error function is used) INPUT PARAMETERS: Network network initialized with one of the network creation funcs X input vector, length of array must be at least NIn DesiredYdesired outputs, length of array must be at least NOut Grad possibly preallocated array. If size of array is smaller than WCount, it will be reallocated. It is recommended to reuse previously allocated array to reduce allocation overhead. OUTPUT PARAMETERS: E error function, sum-of-squares for regression networks, cross-entropy for classification networks. Grad gradient of E with respect to weights of network, array[WCount] -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpgradn( multilayerperceptron network, real_1d_array x, real_1d_array desiredy, double& e, real_1d_array& grad);
mlpgradnbatch
function
/************************************************************************* Batch gradient calculation for a set of inputs/outputs (natural error function is used) INPUT PARAMETERS: Network network initialized with one of the network creation funcs XY set of inputs/outputs; one sample = one row; first NIn columns contain inputs, next NOut columns - desired outputs. SSize number of elements in XY Grad possibly preallocated array. If size of array is smaller than WCount, it will be reallocated. It is recommended to reuse previously allocated array to reduce allocation overhead. OUTPUT PARAMETERS: E error function, sum-of-squares for regression networks, cross-entropy for classification networks. Grad gradient of E with respect to weights of network, array[WCount]
302 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpgradnbatch( multilayerperceptron network, real_2d_array xy, ae_int_t ssize, double& e, real_1d_array& grad);
mlphessianbatch
function
/************************************************************************* Batch Hessian calculation using R-algorithm. Internal subroutine. -- ALGLIB -Copyright 26.01.2008 by Bochkanov Sergey. Hessian calculation based on R-algorithm described in "Fast Exact Multiplication by the Hessian", B. A. Pearlmutter, Neural Computation, 1994. *************************************************************************/ void alglib::mlphessianbatch( multilayerperceptron network, real_2d_array xy, ae_int_t ssize, double& e, real_1d_array& grad, real_2d_array& h);
mlphessiannbatch
function
/************************************************************************* Batch Hessian calculation (natural error function) using R-algorithm. Internal subroutine. -- ALGLIB -Copyright 26.01.2008 by Bochkanov Sergey. Hessian calculation based on R-algorithm described in "Fast Exact Multiplication by the Hessian", B. A. Pearlmutter, Neural Computation, 1994. *************************************************************************/ void alglib::mlphessiannbatch( multilayerperceptron network, real_2d_array xy, ae_int_t ssize, double& e, real_1d_array& grad, real_2d_array& h);
mlpissoftmax
function
/************************************************************************* Tells whether network is SOFTMAX-normalized (i.e. classifier) or not.
303 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ bool alglib::mlpissoftmax(multilayerperceptron network);
mlpprocess
function
/************************************************************************* Procesing INPUT PARAMETERS: Network neural network X input vector, array[0..NIn-1]. OUTPUT PARAMETERS: Y result. Regression estimate when solving regression task, vector of posterior probabilities for classification task. See also MLPProcessI -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpprocess( multilayerperceptron network, real_1d_array x, real_1d_array& y);
mlpprocessi
function
/************************************************************************* 'interactive' variant of MLPProcess for languages like Python which support constructs like "Y = MLPProcess(NN,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 21.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::mlpprocessi( multilayerperceptron network, real_1d_array x, real_1d_array& y);
mlpproperties
function
/************************************************************************* Returns information about initialized network: number of inputs, outputs, weights. -- ALGLIB -Copyright 04.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpproperties(
304 of 430
10/25/2011 03:12 PM
multilayerperceptron network, ae_int_t& nin, ae_int_t& nout, ae_int_t& wcount);
mlprandomize
function
/************************************************************************* Randomization of neural network weights -- ALGLIB -Copyright 06.11.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlprandomize(multilayerperceptron network);
mlprandomizefull
function
/************************************************************************* Randomization of neural network weights and standartisator -- ALGLIB -Copyright 10.03.2008 by Bochkanov Sergey *************************************************************************/ void alglib::mlprandomizefull(multilayerperceptron network);
mlprelclserror
function
/************************************************************************* Relative classification error on the test set INPUT PARAMETERS: Network network XY test set NPoints test set size RESULT: percent of incorrectly classified cases. Works both for classifier networks and general purpose networks used as classifiers. -- ALGLIB -Copyright 25.12.2008 by Bochkanov Sergey *************************************************************************/ double alglib::mlprelclserror( multilayerperceptron network, real_2d_array xy, ae_int_t npoints);
mlprmserror
function
/************************************************************************* RMS error on the test set INPUT PARAMETERS: Network neural network XY test set
305 of 430
10/25/2011 03:12 PM
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 04.11.2007 by Bochkanov Sergey *************************************************************************/ double alglib::mlprmserror( multilayerperceptron network, real_2d_array xy, ae_int_t npoints);
mlpserialize
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. *************************************************************************/ void mlpserialize(multilayerperceptron &obj, std::string &s_out);
mlpsetinputscaling
function
/************************************************************************* This function sets offset/scaling coefficients for I-th input of the network. INPUT PARAMETERS: Network I Mean Sigma network input index mean term sigma term (if zero, will be replaced by 1.0)
NTE: I-th input is passed through linear transformation IN[i] = (IN[i]-Mean)/Sigma before feeding to the network. This function sets Mean and Sigma. -- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mlpsetinputscaling( multilayerperceptron network,
306 of 430
10/25/2011 03:12 PM
ae_int_t i, double mean, double sigma);
mlpsetneuroninfo
function
/************************************************************************* This function modifies information about Ith neuron of Kth layer INPUT PARAMETERS: Network K I FKind Threshold network layer index neuron index (within layer) activation function type (used by MLPActivationFunction()) this value must be zero for input neurons (you can not set activation function for input neurons) also called offset, bias this value must be zero for input neurons (you can not set threshold for input neurons)
NOTES: 1. this function throws exception if layer or neuron with given index do not exists. 2. this function also throws exception when you try to set non-linear activation function for input neurons (any kind of network) or for output neurons of classifier network. 3. this function throws exception when you try to set non-zero threshold for input neurons (any kind of network). -- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mlpsetneuroninfo( multilayerperceptron network, ae_int_t k, ae_int_t i, ae_int_t fkind, double threshold);
mlpsetoutputscaling
function
/************************************************************************* This function sets offset/scaling coefficients for I-th output of the network. INPUT PARAMETERS: Network I Mean Sigma OUTPUT PARAMETERS: NOTE: I-th output is passed through linear transformation OUT[i] = OUT[i]*Sigma+Mean before returning it to user. This function sets Sigma/Mean. In case we have SOFTMAX-normalized network, you can not set (Sigma,Mean) to anything other than(0.0,1.0) - this function will throw exception. -- ALGLIB -network input index mean term sigma term (if zero, will be replaced by 1.0)
307 of 430
10/25/2011 03:12 PM
Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mlpsetoutputscaling( multilayerperceptron network, ae_int_t i, double mean, double sigma);
mlpsetweight
function
/************************************************************************* This function modifies information about connection from I0-th neuron of K0-th layer to I1-th neuron of K1-th layer. INPUT PARAMETERS: Network K0 I0 K1 I1 W network layer index neuron index (within layer) layer index neuron index (within layer) connection weight (must be zero for non-existent connections)
This function: 1. throws exception if layer or neuron with given index do not exists. 2. throws exception if you try to set non-zero weight for non-existent connection -- ALGLIB -Copyright 25.03.2011 by Bochkanov Sergey *************************************************************************/ void alglib::mlpsetweight( multilayerperceptron network, ae_int_t k0, ae_int_t i0, ae_int_t k1, ae_int_t i1, double w);
mlpunserialize
function
/************************************************************************* This function unserializes data structure from string. *************************************************************************/ void mlpunserialize(std::string &s_in, multilayerperceptron &obj);
mlpe
subpackage
Classes
mlpensemble
Functions
mlpeavgce mlpeavgerror mlpeavgrelerror
308 of 430
10/25/2011 03:12 PM
mlpebagginglbfgs mlpebagginglm mlpecreate0 mlpecreate1 mlpecreate2 mlpecreateb0 mlpecreateb1 mlpecreateb2 mlpecreatec0 mlpecreatec1 mlpecreatec2 mlpecreatefromnetwork mlpecreater0 mlpecreater1 mlpecreater2 mlpeissoftmax mlpeprocess mlpeprocessi mlpeproperties mlperandomize mlperelclserror mlpermserror mlpetraines
Examples
mlpensemble
class
/************************************************************************* Neural networks ensemble *************************************************************************/ class mlpensemble { };
mlpeavgce
function
/************************************************************************* Average cross-entropy (in bits per element) on the test set INPUT PARAMETERS: Ensembleensemble XY test set NPoints test set size RESULT: CrossEntropy/(NPoints*LN(2)). Zero if ensemble solves regression task. -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ double alglib::mlpeavgce( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints);
309 of 430
10/25/2011 03:12 PM
mlpeavgerror
function
/************************************************************************* Average error on the test set INPUT PARAMETERS: Ensembleensemble 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 17.02.2009 by Bochkanov Sergey *************************************************************************/ double alglib::mlpeavgerror( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints);
mlpeavgrelerror
function
/************************************************************************* Average relative error on the test set INPUT PARAMETERS: Ensembleensemble 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 probabilities. -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ double alglib::mlpeavgrelerror( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints);
mlpebagginglbfgs
function
/************************************************************************* Training neural networks ensemble using bootstrap aggregating (bagging). L-BFGS algorithm is used as base training method. INPUT PARAMETERS: Ensemble XY NPoints Decay Restarts WStep MaxIts model with initialized geometry training set training set size weight decay coefficient, >=0.001 restarts, >0. stopping criterion, same as in MLPTrainLBFGS stopping criterion, same as in MLPTrainLBFGS
310 of 430
10/25/2011 03:12 PM
OUTPUT PARAMETERS: Ensemble Info -
Rep OOBErrors
trained model return code: * -8, if both WStep=0 and MaxIts=0 * -2, if there is a point with class number outside of [0..NClasses-1]. * -1, if incorrect parameters was passed (NPoints<0, Restarts<1). * 2, if task has been solved. training report. out-of-bag generalization error estimate
-- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpebagginglbfgs( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints, double decay, ae_int_t restarts, double wstep, ae_int_t maxits, ae_int_t& info, mlpreport& rep, mlpcvreport& ooberrors);
mlpebagginglm
function
/************************************************************************* Training neural networks ensemble using bootstrap aggregating (bagging). Modified Levenberg-Marquardt algorithm is used as base training method. INPUT PARAMETERS: Ensemble XY NPoints Decay Restarts OUTPUT PARAMETERS: Ensemble Info model with initialized geometry training set training set size weight decay coefficient, >=0.001 restarts, >0. trained model return code: * -2, if there is a point with class number outside of [0..NClasses-1]. * -1, if incorrect parameters was passed (NPoints<0, Restarts<1). * 2, if task has been solved. training report. out-of-bag generalization error estimate
Rep OOBErrors
-- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpebagginglm( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints, double decay, ae_int_t restarts, ae_int_t& info, mlpreport& rep,
311 of 430
10/25/2011 03:12 PM
mlpcvreport& ooberrors);
mlpecreate0
function
/************************************************************************* Like MLPCreate0, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreate0( ae_int_t nin, ae_int_t nout, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreate1
function
/************************************************************************* Like MLPCreate1, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreate1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreate2
function
/************************************************************************* Like MLPCreate2, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreate2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreateb0
function
/************************************************************************* Like MLPCreateB0, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreateb0(
312 of 430
10/25/2011 03:12 PM
ae_int_t nin, ae_int_t nout, double b, double d, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreateb1
function
/************************************************************************* Like MLPCreateB1, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreateb1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, double b, double d, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreateb2
function
/************************************************************************* Like MLPCreateB2, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreateb2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, double b, double d, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreatec0
function
/************************************************************************* Like MLPCreateC0, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreatec0( ae_int_t nin, ae_int_t nout, ae_int_t ensemblesize, mlpensemble& ensemble);
313 of 430
10/25/2011 03:12 PM
mlpecreatec1
function
/************************************************************************* Like MLPCreateC1, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreatec1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreatec2
function
/************************************************************************* Like MLPCreateC2, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreatec2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreatefromnetwork
function
/************************************************************************* Creates ensemble from network. Only network geometry is copied. -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreatefromnetwork( multilayerperceptron network, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreater0
function
/************************************************************************* Like MLPCreateR0, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreater0( ae_int_t nin, ae_int_t nout, double a, double b,
314 of 430
10/25/2011 03:12 PM
ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreater1
function
/************************************************************************* Like MLPCreateR1, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreater1( ae_int_t nin, ae_int_t nhid, ae_int_t nout, double a, double b, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpecreater2
function
/************************************************************************* Like MLPCreateR2, but for ensembles. -- ALGLIB -Copyright 18.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpecreater2( ae_int_t nin, ae_int_t nhid1, ae_int_t nhid2, ae_int_t nout, double a, double b, ae_int_t ensemblesize, mlpensemble& ensemble);
mlpeissoftmax
function
/************************************************************************* Return normalization type (whether ensemble is SOFTMAX-normalized or not). -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ bool alglib::mlpeissoftmax(mlpensemble ensemble);
mlpeprocess
function
/************************************************************************* Procesing INPUT PARAMETERS: Ensembleneural networks ensemble X input vector, array[0..NIn-1].
315 of 430
10/25/2011 03:12 PM
Y (possibly) preallocated buffer; if size of Y is less than NOut, 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. Regression estimate when solving regression task, vector of posterior probabilities for classification task. -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpeprocess( mlpensemble ensemble, real_1d_array x, real_1d_array& y);
mlpeprocessi
function
/************************************************************************* 'interactive' variant of MLPEProcess for languages like Python which support constructs like "Y = MLPEProcess(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 17.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpeprocessi( mlpensemble ensemble, real_1d_array x, real_1d_array& y);
mlpeproperties
function
/************************************************************************* Return ensemble properties (number of inputs and outputs). -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpeproperties( mlpensemble ensemble, ae_int_t& nin, ae_int_t& nout);
mlperandomize
function
/************************************************************************* Randomization of MLP ensemble -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlperandomize(mlpensemble ensemble);
316 of 430
10/25/2011 03:12 PM
mlperelclserror
function
/************************************************************************* Relative classification error on the test set INPUT PARAMETERS: Ensembleensemble XY test set NPoints test set size RESULT: percent of incorrectly classified cases. Works both for classifier betwork and for regression networks which are used as classifiers. -- ALGLIB -Copyright 17.02.2009 by Bochkanov Sergey *************************************************************************/ double alglib::mlperelclserror( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints);
mlpermserror
function
/************************************************************************* RMS error on the test set INPUT PARAMETERS: Ensembleensemble 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 17.02.2009 by Bochkanov Sergey *************************************************************************/ double alglib::mlpermserror( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints);
mlpetraines
function
/************************************************************************* Training neural networks ensemble using early stopping. INPUT PARAMETERS: Ensemble XY NPoints Decay Restarts model with initialized geometry training set training set size weight decay coefficient, >=0.001 restarts, >0.
317 of 430
10/25/2011 03:12 PM
OUTPUT PARAMETERS: Ensemble Info -
Rep OOBErrors
trained model return code: * -2, if there is a point with class number outside of [0..NClasses-1]. * -1, if incorrect parameters was passed (NPoints<0, Restarts<1). * 6, if task has been solved. training report. out-of-bag generalization error estimate
-- ALGLIB -Copyright 10.03.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlpetraines( mlpensemble ensemble, real_2d_array xy, ae_int_t npoints, double decay, ae_int_t restarts, ae_int_t& info, mlpreport& rep);
mlptrain
Classes
mlpcvreport mlpreport
subpackage
Functions
mlpkfoldcvlbfgs mlpkfoldcvlm mlptraines mlptrainlbfgs mlptrainlm
Examples
mlpcvreport
class
/************************************************************************* Cross-validation estimates of generalization error *************************************************************************/ class mlpcvreport { double relclserror; double avgce; double rmserror; double avgerror; double avgrelerror; };
318 of 430
10/25/2011 03:12 PM
mlpreport
class
/************************************************************************* Training report: * NGrad - number of gradient calculations * NHess - number of Hessian calculations * NCholesky - number of Cholesky decompositions *************************************************************************/ class mlpreport { ae_int_t ngrad; ae_int_t nhess; ae_int_t ncholesky; };
mlpkfoldcvlbfgs
function
/************************************************************************* Cross-validation estimate of generalization error. Base algorithm - L-BFGS. INPUT PARAMETERS: Network XY SSize Decay Restarts WStep MaxIts FoldsCount neural network with initialized geometry. Network is not changed during cross-validation - it is used only as a representative of its architecture. training set. training set size weight decay, same as in MLPTrainLBFGS number of restarts, >0. restarts are counted for each partition separately, so total number of restarts will be Restarts*FoldsCount. stopping criterion, same as in MLPTrainLBFGS stopping criterion, same as in MLPTrainLBFGS number of folds in k-fold cross-validation, 2<=FoldsCount<=SSize. recommended value: 10. return code, same as in MLPTrainLBFGS report, same as in MLPTrainLM/MLPTrainLBFGS generalization error estimates
OUTPUT PARAMETERS: Info Rep CVRep -
-- ALGLIB -Copyright 09.12.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpkfoldcvlbfgs( multilayerperceptron network, real_2d_array xy, ae_int_t npoints, double decay, ae_int_t restarts, double wstep, ae_int_t maxits, ae_int_t foldscount, ae_int_t& info, mlpreport& rep, mlpcvreport& cvrep);
319 of 430
10/25/2011 03:12 PM
mlpkfoldcvlm
function
/************************************************************************* Cross-validation estimate of generalization error. Base algorithm - Levenberg-Marquardt. INPUT PARAMETERS: Network XY SSize Decay Restarts FoldsCount neural network with initialized geometry. Network is not changed during cross-validation - it is used only as a representative of its architecture. training set. training set size weight decay, same as in MLPTrainLBFGS number of restarts, >0. restarts are counted for each partition separately, so total number of restarts will be Restarts*FoldsCount. number of folds in k-fold cross-validation, 2<=FoldsCount<=SSize. recommended value: 10. return code, same as in MLPTrainLBFGS report, same as in MLPTrainLM/MLPTrainLBFGS generalization error estimates
OUTPUT PARAMETERS: Info Rep CVRep -
-- ALGLIB -Copyright 09.12.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlpkfoldcvlm( multilayerperceptron network, real_2d_array xy, ae_int_t npoints, double decay, ae_int_t restarts, ae_int_t foldscount, ae_int_t& info, mlpreport& rep, mlpcvreport& cvrep);
mlptraines
function
/************************************************************************* Neural network training using early stopping (base algorithm - L-BFGS with regularization). INPUT PARAMETERS: Network TrnXY TrnSize ValXY ValSize Decay neural network with initialized geometry training set training set size validation set validation set size weight decay constant, >=0.001 Decay term 'Decay*||Weights||^2' is added to error function. If you don't know what Decay to choose, use 0.001. number of restarts from random position, >0. If you don't know what Restarts to choose, use 2. trained neural network.
Restarts
OUTPUT PARAMETERS: Network -
320 of 430
10/25/2011 03:12 PM
Info return code: * -2, if there is a point with class number outside of [0..NOut-1]. * -1, if wrong parameters specified (NPoints<0, Restarts<1, ...). * 2, task has been solved, stopping criterion met sufficiently small step size. Not expected (we use EARLY stopping) but possible and not an error. * 6, task has been solved, stopping criterion met increasing of validation set error. training report
Rep NOTE:
Algorithm stops if validation set error increases for a long enough or step size is small enought (there are task where validation set may decrease for eternity). In any case solution returned corresponds to the minimum of validation set error. -- ALGLIB -Copyright 10.03.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlptraines( multilayerperceptron network, real_2d_array trnxy, ae_int_t trnsize, real_2d_array valxy, ae_int_t valsize, double decay, ae_int_t restarts, ae_int_t& info, mlpreport& rep);
mlptrainlbfgs
function
/************************************************************************* Neural network training using L-BFGS algorithm with regularization. Subroutine trains neural network with restarts from random positions. Algorithm is well suited for problems of any dimensionality (memory requirements and step complexity are linear by weights number). INPUT PARAMETERS: Network XY NPoints Decay neural network with initialized geometry training set training set size weight decay constant, >=0.001 Decay term 'Decay*||Weights||^2' is added to error function. If you don't know what Decay to choose, use 0.001. number of restarts from random position, >0. If you don't know what Restarts to choose, use 2. stopping criterion. Algorithm stops if step size is less than WStep. Recommended value - 0.01. Zero step size means stopping after MaxIts iterations. stopping criterion. Algorithm stops after MaxIts iterations (NOT gradient calculations). Zero MaxIts means stopping when step is sufficiently small. trained neural network. return code:
Restarts WStep MaxIts
OUTPUT PARAMETERS: Network Info -
321 of 430
10/25/2011 03:12 PM
* -8, if both WStep=0 and MaxIts=0 * -2, if there is a point with class number outside of [0..NOut-1]. * -1, if wrong parameters specified (NPoints<0, Restarts<1). * 2, if task has been solved. training report
Rep
-- ALGLIB -Copyright 09.12.2007 by Bochkanov Sergey *************************************************************************/ void alglib::mlptrainlbfgs( multilayerperceptron network, real_2d_array xy, ae_int_t npoints, double decay, ae_int_t restarts, double wstep, ae_int_t maxits, ae_int_t& info, mlpreport& rep);
mlptrainlm
function
/************************************************************************* Neural network training using modified Levenberg-Marquardt with exact Hessian calculation and regularization. Subroutine trains neural network with restarts from random positions. Algorithm is well suited for small and medium scale problems (hundreds of weights). INPUT PARAMETERS: Network XY NPoints Decay neural network with initialized geometry training set training set size weight decay constant, >=0.001 Decay term 'Decay*||Weights||^2' is added to error function. If you don't know what Decay to choose, use 0.001. number of restarts from random position, >0. If you don't know what Restarts to choose, use 2. trained neural network. return code: * -9, if internal matrix inverse subroutine failed * -2, if there is a point with class number outside of [0..NOut-1]. * -1, if wrong parameters specified (NPoints<0, Restarts<1). * 2, if task has been solved. training report
Restarts
OUTPUT PARAMETERS: Network Info -
Rep
-- ALGLIB -Copyright 10.03.2009 by Bochkanov Sergey *************************************************************************/ void alglib::mlptrainlm( multilayerperceptron network, real_2d_array xy, ae_int_t npoints, double decay, ae_int_t restarts, ae_int_t& info,
322 of 430
10/25/2011 03:12 PM
mlpreport& rep);
nearestneighbor
Classes
kdtree
subpackage
Functions
kdtreebuild kdtreebuildtagged kdtreequeryaknn kdtreequeryknn kdtreequeryresultsdistanc es kdtreequeryresultsdistanc esi kdtreequeryresultstags kdtreequeryresultstagsi kdtreequeryresultsx kdtreequeryresultsxi kdtreequeryresultsxy kdtreequeryresultsxyi kdtreequeryrnn kdtreeserialize kdtreeunserialize
Examples
nneighbor_d_1 nneighbor_d_2 Nearest neighbor searc h, KNN queries Serialization of KD-trees
kdtree
class
/************************************************************************* *************************************************************************/ class kdtree { };
kdtreebuild
function
/************************************************************************* KD-tree creation This subroutine creates KD-tree from set of X-values and optional Y-values INPUT PARAMETERS XY dataset, array[0..N-1,0..NX+NY-1]. one row corresponds to one point. first NX columns contain X-values, next NY (NY may be zero) columns may contain associated Y-values N number of points, N>=1 NX space dimension, NX>=1. NY number of optional Y-values, NY>=0.
323 of 430
10/25/2011 03:12 PM
NormTypenorm type: * 0 denotes infinity-norm * 1 denotes 1-norm * 2 denotes 2-norm (Euclidean norm)
OUTPUT PARAMETERS KDT KD-tree NOTES 1. KD-tree creation have O(N*logN) complexity and O(N*(2*NX+NY)) memory requirements. 2. Although KD-trees may be used with any combination of N and NX, they are more efficient than brute-force search only when N >> 4^NX. So they are most useful in low-dimensional tasks (NX=2, NX=3). NX=1 is another inefficient case, because simple binary search (without additional structures) is much more efficient in such tasks than KD-trees. -- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::kdtreebuild( real_2d_array xy, ae_int_t nx, ae_int_t ny, ae_int_t normtype, kdtree& kdt); void alglib::kdtreebuild( real_2d_array xy, ae_int_t n, ae_int_t nx, ae_int_t ny, ae_int_t normtype, kdtree& kdt); Examples: [1] [2]
kdtreebuildtagged
function
/************************************************************************* KD-tree creation This subroutine creates optional Y-values KD-tree from set of X-values, integer tags and
INPUT PARAMETERS XY dataset, array[0..N-1,0..NX+NY-1]. one row corresponds to one point. first NX columns contain X-values, next NY (NY may be zero) columns may contain associated Y-values Tags tags, array[0..N-1], contains integer tags associated with points. N number of points, N>=1 NX space dimension, NX>=1. NY number of optional Y-values, NY>=0. NormTypenorm type: * 0 denotes infinity-norm * 1 denotes 1-norm * 2 denotes 2-norm (Euclidean norm) OUTPUT PARAMETERS
324 of 430
10/25/2011 03:12 PM
KDT NOTES 1. KD-tree creation have O(N*logN) complexity and O(N*(2*NX+NY)) memory requirements. 2. Although KD-trees may be used with any combination of N and NX, they are more efficient than brute-force search only when N >> 4^NX. So they are most useful in low-dimensional tasks (NX=2, NX=3). NX=1 is another inefficient case, because simple binary search (without additional structures) is much more efficient in such tasks than KD-trees. -- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::kdtreebuildtagged( real_2d_array xy, integer_1d_array tags, ae_int_t nx, ae_int_t ny, ae_int_t normtype, kdtree& kdt); void alglib::kdtreebuildtagged( real_2d_array xy, integer_1d_array tags, ae_int_t n, ae_int_t nx, ae_int_t ny, ae_int_t normtype, kdtree& kdt); Examples: [1] KD-tree
kdtreequeryaknn
function
/************************************************************************* K-NN query: approximate K nearest neighbors INPUT PARAMETERS KDT X K SelfMatch KD-tree point, array[0..NX-1]. number of neighbors to return, K>=1 whether self-matches are allowed: * if True, nearest neighbor may be the point itself (if it exists in original dataset) * if False, then only points with non-zero distance are returned * if not given, considered True approximation factor, Eps>=0. eps-approximate nearest neighbor is a neighbor whose distance from X is at most (1+eps) times distance of true nearest neighbor.
Eps
RESULT number of actual neighbors found (either K or N, if K>N). NOTES significant performance gain may be achieved only when Eps the order of magnitude of 1 or larger. This subroutine performs query and structures of the KD-tree. You can use these results: is is on
stores its result in the internal following subroutines to obtain
325 of 430
10/25/2011 03:12 PM
* * * * KDTreeQueryResultsX() to get X-values KDTreeQueryResultsXY() to get X- and Y-values KDTreeQueryResultsTags() to get tag values KDTreeQueryResultsDistances() to get distances
-- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::kdtreequeryaknn( kdtree kdt, real_1d_array x, ae_int_t k, double eps); ae_int_t alglib::kdtreequeryaknn( kdtree kdt, real_1d_array x, ae_int_t k, bool selfmatch, double eps); Examples: [1]
kdtreequeryknn
function
/************************************************************************* K-NN query: K nearest neighbors INPUT PARAMETERS KDT X K SelfMatch KD-tree point, array[0..NX-1]. number of neighbors to return, K>=1 whether self-matches are allowed: * if True, nearest neighbor may be the point itself (if it exists in original dataset) * if False, then only points with non-zero distance are returned * if not given, considered True
RESULT number of actual neighbors found (either K or N, if K>N). This subroutine performs query and stores its result in the internal structures of the KD-tree. You can use following subroutines to obtain these results: * KDTreeQueryResultsX() to get X-values * KDTreeQueryResultsXY() to get X- and Y-values * KDTreeQueryResultsTags() to get tag values * KDTreeQueryResultsDistances() to get distances -- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::kdtreequeryknn(kdtree kdt, real_1d_array x, ae_int_t k); ae_int_t alglib::kdtreequeryknn( kdtree kdt, real_1d_array x, ae_int_t k, bool selfmatch); Examples: [1]
326 of 430
10/25/2011 03:12 PM
kdtreequeryresultsdistances
function
/************************************************************************* Distances from last query INPUT PARAMETERS KDT KD-tree R possibly pre-allocated buffer. If X is too small to store result, it is resized. If size(X) is enough to store result, it is left unchanged. OUTPUT PARAMETERS R filled with distances (in corresponding norm) NOTES 1. points are ordered by distance from the query point (first = closest) 2. if XY is larger than required to store result, only leading part will be overwritten; trailing part will be left unchanged. So if on input XY = [[A,B],[C,D]], and result is [1,2], then on exit we will get XY = [[1,2],[C,D]]. This is done purposely to increase performance; if you want function to resize array according to result size, use function with same name and suffix 'I'. SEE ALSO * KDTreeQueryResultsX() * KDTreeQueryResultsXY() * KDTreeQueryResultsTags() X-values X- and Y-values tag values
-- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::kdtreequeryresultsdistances(kdtree kdt, real_1d_array& r); Examples: [1]
kdtreequeryresultsdistancesi
function
/************************************************************************* Distances from last query; 'interactive' variant for languages like Python which support constructs like "R = KDTreeQueryResultsDistancesI(KDT)" 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 *************************************************************************/ void alglib::kdtreequeryresultsdistancesi(kdtree kdt, real_1d_array& r);
kdtreequeryresultstags
function
/************************************************************************* Tags from last query INPUT PARAMETERS KDT KD-tree Tags possibly pre-allocated buffer. If X is too small to store
327 of 430
10/25/2011 03:12 PM
result, it is resized. If size(X) is enough to store result, it is left unchanged. OUTPUT PARAMETERS Tags filled with tags associated with points, or, when no tags were supplied, with zeros NOTES 1. points are ordered by distance from the query point (first = closest) 2. if XY is larger than required to store result, only leading part will be overwritten; trailing part will be left unchanged. So if on input XY = [[A,B],[C,D]], and result is [1,2], then on exit we will get XY = [[1,2],[C,D]]. This is done purposely to increase performance; if you want function to resize array according to result size, use function with same name and suffix 'I'. SEE ALSO * KDTreeQueryResultsX() * KDTreeQueryResultsXY() * KDTreeQueryResultsDistances() X-values X- and Y-values distances
-- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::kdtreequeryresultstags(kdtree kdt, integer_1d_array& tags); Examples: [1]
kdtreequeryresultstagsi
function
/************************************************************************* Tags from last query; 'interactive' variant for languages like Python which support constructs like "Tags = KDTreeQueryResultsTagsI(KDT)" 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 *************************************************************************/ void alglib::kdtreequeryresultstagsi(kdtree kdt, integer_1d_array& tags);
kdtreequeryresultsx
function
/************************************************************************* X-values from last query INPUT PARAMETERS KDT KD-tree X possibly pre-allocated buffer. If X is too small to store result, it is resized. If size(X) is enough to store result, it is left unchanged. OUTPUT PARAMETERS X rows are filled with X-values NOTES 1. points are ordered by distance from the query point (first = closest)
328 of 430
10/25/2011 03:12 PM
2. if XY is larger than required to store result, only leading part will be overwritten; trailing part will be left unchanged. So if on input XY = [[A,B],[C,D]], and result is [1,2], then on exit we will get XY = [[1,2],[C,D]]. This is done purposely to increase performance; if you want function to resize array according to result size, use function with same name and suffix 'I'. SEE ALSO * KDTreeQueryResultsXY() * KDTreeQueryResultsTags() * KDTreeQueryResultsDistances() X- and Y-values tag values distances
-- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::kdtreequeryresultsx(kdtree kdt, real_2d_array& x); Examples: [1]
kdtreequeryresultsxi
function
/************************************************************************* X-values from last query; 'interactive' variant for languages like Python which support constructs like "X = KDTreeQueryResultsXI(KDT)" 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 *************************************************************************/ void alglib::kdtreequeryresultsxi(kdtree kdt, real_2d_array& x);
kdtreequeryresultsxy
function
/************************************************************************* X- and Y-values from last query INPUT PARAMETERS KDT KD-tree XY possibly pre-allocated buffer. If XY is too small to store result, it is resized. If size(XY) is enough to store result, it is left unchanged. OUTPUT PARAMETERS XY rows are filled with points: first NX columns with X-values, next NY columns - with Y-values. NOTES 1. points are ordered by distance from the query point (first = closest) 2. if XY is larger than required to store result, only leading part will be overwritten; trailing part will be left unchanged. So if on input XY = [[A,B],[C,D]], and result is [1,2], then on exit we will get XY = [[1,2],[C,D]]. This is done purposely to increase performance; if you want function to resize array according to result size, use function with same name and suffix 'I'. SEE ALSO
329 of 430
10/25/2011 03:12 PM
* KDTreeQueryResultsX() * KDTreeQueryResultsTags() * KDTreeQueryResultsDistances() X-values tag values distances
-- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ void alglib::kdtreequeryresultsxy(kdtree kdt, real_2d_array& xy); Examples: [1]
kdtreequeryresultsxyi
function
/************************************************************************* XY-values from last query; 'interactive' variant for languages like Python which support constructs like "XY = KDTreeQueryResultsXYI(KDT)" 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 *************************************************************************/ void alglib::kdtreequeryresultsxyi(kdtree kdt, real_2d_array& xy);
kdtreequeryrnn
function
/************************************************************************* R-NN query: all points within R-sphere centered at X INPUT PARAMETERS KDT X R SelfMatch KD-tree point, array[0..NX-1]. radius of sphere (in corresponding norm), R>0 whether self-matches are allowed: * if True, nearest neighbor may be the point itself (if it exists in original dataset) * if False, then only points with non-zero distance are returned * if not given, considered True
RESULT number of neighbors found, >=0 This subroutine performs query and stores its result in the internal structures of the KD-tree. You can use following subroutines to obtain actual results: * KDTreeQueryResultsX() to get X-values * KDTreeQueryResultsXY() to get X- and Y-values * KDTreeQueryResultsTags() to get tag values * KDTreeQueryResultsDistances() to get distances -- ALGLIB -Copyright 28.02.2010 by Bochkanov Sergey *************************************************************************/ ae_int_t alglib::kdtreequeryrnn(kdtree kdt, real_1d_array x, double r); ae_int_t alglib::kdtreequeryrnn( kdtree kdt,
330 of 430
10/25/2011 03:12 PM
real_1d_array x, double r, bool selfmatch); Examples: [1]
kdtreeserialize
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. *************************************************************************/ void kdtreeserialize(kdtree &obj, std::string &s_out);
kdtreeunserialize
function
/************************************************************************* This function unserializes data structure from string. *************************************************************************/ void kdtreeunserialize(std::string &s_in, kdtree &obj);
nneighbor_d_1 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "alglibmisc.h"
using namespace alglib; int main(int argc, char **argv) { real_2d_array a = "[[0,0],[0,1],[1,0],[1,1]]"; ae_int_t nx = 2; ae_int_t ny = 0; ae_int_t normtype = 2; kdtree kdt; real_1d_array x; real_2d_array r = "[[]]"; ae_int_t k; kdtreebuild(a, nx, ny, normtype, kdt); x = "[-1,0]";
331 of 430
10/25/2011 03:12 PM
k = kdtreequeryknn(kdt, x, 1); printf("%d\n", int(k)); // EXPECTED: 1 kdtreequeryresultsx(kdt, r); printf("%s\n", r.tostring(1).c_str()); // EXPECTED: [[0,0]] return 0; }
nneighbor_d_2 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "alglibmisc.h"
using namespace alglib; int main(int argc, char **argv) { real_2d_array a = "[[0,0],[0,1],[1,0],[1,1]]"; ae_int_t nx = 2; ae_int_t ny = 0; ae_int_t normtype = 2; kdtree kdt0; kdtree kdt1; std::string s; real_1d_array x; real_2d_array r0 = "[[]]"; real_2d_array r1 = "[[]]"; // // Build tree and serialize it // kdtreebuild(a, nx, ny, normtype, kdt0); alglib::kdtreeserialize(kdt0, s); alglib::kdtreeunserialize(s, kdt1); // // Compare results from KNN queries // x = "[-1,0]"; kdtreequeryknn(kdt0, x, 1); kdtreequeryresultsx(kdt0, r0); kdtreequeryknn(kdt1, x, 1); kdtreequeryresultsx(kdt1, r1); printf("%s\n", r0.tostring(1).c_str()); // EXPECTED: [[0,0]] printf("%s\n", r1.tostring(1).c_str()); // EXPECTED: [[0,0]] return 0; }
nleq
subpackage
Classes
nleqreport nleqstate
332 of 430
10/25/2011 03:12 PM
Functions
nleqcreatelm nleqrestartfrom nleqresults nleqresultsbuf nleqsetcond nleqsetstpmax nleqsetxrep nleqsolve
Examples
nleqreport
class
/************************************************************************* *************************************************************************/ class nleqreport { ae_int_t iterationscount; ae_int_t nfunc; ae_int_t njac; ae_int_t terminationtype; };
nleqstate
class
/************************************************************************* *************************************************************************/ class nleqstate { };
nleqcreatelm
function
/************************************************************************* LEVENBERG-MARQUARDT-LIKE NONLINEAR SOLVER DESCRIPTION: This algorithm solves system of nonlinear equations F[0](x[0], ..., x[n-1]) = 0 F[1](x[0], ..., x[n-1]) = 0 ... F[M-1](x[0], ..., x[n-1]) = 0 with M/N do not necessarily coincide. Algorithm converges quadratically under following conditions: * the solution set XS is nonempty * for some xs in XS there exist such neighbourhood N(xs) that: * vector function F(x) and its Jacobian J(x) are continuously differentiable on N * ||F(x)|| provides local error bound on N, i.e. there exists such c1, that ||F(x)||>c1*distance(x,XS) Note that these conditions are much more weaker than usual non-singularity conditions. For example, algorithm will converge for any affine function
333 of 430
10/25/2011 03:12 PM
F (whether its Jacobian singular or not). REQUIREMENTS: Algorithm will request following information during its operation: * function vector F[] and Jacobian matrix at given point X * value of merit function f(x)=F[0]^2(x)+...+F[M-1]^2(x) at given point X USAGE: 1. User initializes algorithm state with NLEQCreateLM() call 2. User tunes solver parameters with NLEQSetCond(), NLEQSetStpMax() and other functions 3. User calls NLEQSolve() function which takes algorithm state and pointers (delegates, etc.) to callback functions which calculate merit function value and Jacobian. 4. User calls NLEQResults() to get solution 5. Optionally, user may call NLEQRestartFrom() to solve another problem with same parameters (N/M) but another starting point and/or another function vector. NLEQRestartFrom() allows to reuse already initialized structure. INPUT PARAMETERS: N space dimension, N>1: * if provided, only leading N elements of X are used * if not provided, determined automatically from size of X M system size X starting point OUTPUT PARAMETERS: State structure which stores algorithm state NOTES: 1. you may tune stopping conditions with NLEQSetCond() function 2. if target function contains exp() or other fast growing functions, and optimization algorithm makes too large steps which leads to overflow, use NLEQSetStpMax() function to bound algorithm's steps. 3. this algorithm is a slightly modified implementation of the method described in 'Levenberg-Marquardt method for constrained nonlinear equations with strong local convergence properties' by Christian Kanzow Nobuo Yamashita and Masao Fukushima and further developed in 'On the convergence of a New Levenberg-Marquardt Method' by Jin-yan Fan and Ya-Xiang Yuan. -- ALGLIB -Copyright 20.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::nleqcreatelm(ae_int_t m, real_1d_array x, nleqstate& state); void alglib::nleqcreatelm( ae_int_t n, ae_int_t m, real_1d_array x, nleqstate& state);
nleqrestartfrom
function
/************************************************************************* This subroutine restarts CG algorithm from new point. All optimization
334 of 430
10/25/2011 03:12 PM
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 MinCGCreate call. X new starting point. BndL new lower bounds BndU new upper bounds -- ALGLIB -Copyright 30.07.2010 by Bochkanov Sergey *************************************************************************/ void alglib::nleqrestartfrom(nleqstate state, real_1d_array x);
nleqresults
function
/************************************************************************* NLEQ solver results INPUT PARAMETERS: State algorithm state. OUTPUT PARAMETERS: X array[0..N-1], solution Rep optimization report: * Rep.TerminationType completetion code: * -4 ERROR: algorithm has converged to the stationary point Xf which is local minimum of f=F[0]^2+...+F[m-1]^2, but is not solution of nonlinear system. * 1 sqrt(f)<=EpsF. * 5 MaxIts steps was taken * 7 stopping conditions are too stringent, further improvement is impossible * Rep.IterationsCount contains iterations count * NFEV countains number of function calculations * ActiveConstraints contains number of active constraints -- ALGLIB -Copyright 20.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::nleqresults( nleqstate state, real_1d_array& x, nleqreport& rep);
nleqresultsbuf
function
/************************************************************************* NLEQ solver results Buffered implementation of NLEQResults(), 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 --
335 of 430
10/25/2011 03:12 PM
Copyright 20.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::nleqresultsbuf( nleqstate state, real_1d_array& x, nleqreport& rep);
nleqsetcond
function
/************************************************************************* This function sets stopping conditions for the nonlinear solver INPUT PARAMETERS: State structure which stores algorithm state EpsF >=0 The subroutine finishes its work if on k+1-th iteration the condition ||F||<=EpsF is satisfied MaxIts maximum number of iterations. If MaxIts=0, the number of iterations is unlimited. Passing EpsF=0 and MaxIts=0 simultaneously will lead to stopping criterion selection (small EpsF). NOTES: -- ALGLIB -Copyright 20.08.2010 by Bochkanov Sergey *************************************************************************/ void alglib::nleqsetcond(nleqstate state, double epsf, ae_int_t maxits); automatic
nleqsetstpmax
function
if you don't
Use this subroutine when target function contains exp() or other fast growing functions, and 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 20.08.2010 by Bochkanov Sergey *************************************************************************/ void alglib::nleqsetstpmax(nleqstate state, double stpmax);
nleqsetxrep
function
/************************************************************************* This function turns on/off reporting. INPUT PARAMETERS: State structure which stores algorithm state
336 of 430
10/25/2011 03:12 PM
NeedXRepwhether iteration reports are needed or not it is
If NeedXRep is True, algorithm will call rep() callback function if provided to NLEQSolve().
-- ALGLIB -Copyright 20.08.2010 by Bochkanov Sergey *************************************************************************/ void alglib::nleqsetxrep(nleqstate state, bool needxrep);
nleqsolve
function
/************************************************************************* This family of functions is used to launcn iterations of nonlinear solver These functions accept following parameters: state algorithm state func callback which calculates function (or merit function) value func 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 -- ALGLIB -Copyright 20.03.2009 by Bochkanov Sergey *************************************************************************/ void nleqsolve(nleqstate &state, void (*func)(const real_1d_array &x, double &func, void *ptr), void (*jac)(const real_1d_array &x, real_1d_array &fi, real_2d_array &jac, void *ptr), void (*rep)(const real_1d_array &x, double func, void *ptr) = NULL, void *ptr = NULL);
normaldistr
Functions
errorfunction errorfunctionc inverf invnormaldistribution normaldistribution
subpackage
Examples
errorfunction
function
/************************************************************************* Error function The integral is x -
337 of 430
10/25/2011 03:12 PM
2 -------sqrt(pi) | | | | | 0 2 exp( - t ) dt.
erf(x)
For 0 <= |x| < 1, erf(x) = x * P4(x**2)/Q5(x**2); otherwise erf(x) = 1 - erfc(x). ACCURACY: arithmetic IEEE domain 0,1 Relative error: # trials peak 30000 3.7e-16 rms 1.0e-16
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1988, 1992, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::errorfunction(double x);
errorfunctionc
function
/************************************************************************* Complementary error function 1 - erf(x) = inf. | | | | | x
erfc(x)
2 -------sqrt(pi)
2 exp( - t ) dt
For small x, erfc(x) = 1 - erf(x); otherwise rational approximations are computed. ACCURACY: arithmetic IEEE Relative error: domain # trials peak 0,26.6417 30000 5.7e-14 rms 1.5e-14
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1988, 1992, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::errorfunctionc(double x);
inverf
function
/************************************************************************* Inverse of the error function Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1988, 1992, 2000 by Stephen L. Moshier *************************************************************************/
338 of 430
10/25/2011 03:12 PM
double alglib::inverf(double e);
invnormaldistribution
function
/************************************************************************* Inverse of Normal distribution function Returns the argument, x, for which the area under the Gaussian probability density function (integrated from minus infinity to x) is equal to y. For small arguments 0 < y < exp(-2), the program computes z = sqrt( -2.0 * log(y) ); then the approximation is x = z - log(z)/z - (1/z) P(1/z) / Q(1/z). There are two rational functions P/Q, one for 0 < y < exp(-32) and the other for y up to exp(-2). For larger arguments, w = y - 0.5, and x/sqrt(2pi) = w + w**3 R(w**2)/S(w**2)). ACCURACY: arithmetic IEEE IEEE Relative error: domain # trials 0.125, 1 20000 3e-308, 0.135 50000 peak 7.2e-16 4.6e-16 rms 1.3e-16 9.8e-17
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1988, 1992, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::invnormaldistribution(double y0);
normaldistribution
function
/************************************************************************* Normal distribution function Returns the area under the Gaussian probability density function, integrated from minus infinity to x: x | | | | | -inf.
ndtr(x)
1 = --------sqrt(2pi)
2 exp( - t /2 ) dt
= =
( 1 + erf(z) ) / 2 erfc(z) / 2
where z = x/sqrt(2). Computation is via the functions erf and erfc. ACCURACY: arithmetic IEEE domain -13,0 Relative error: # trials peak 30000 3.4e-14 rms 6.7e-15
339 of 430
10/25/2011 03:12 PM
Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1988, 1992, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::normaldistribution(double x);
odesolver
Classes
odesolverreport odesolverstate
subpackage
Functions
odesolverresults odesolverrkck odesolversolve
Examples
odesolver_d1 Solving y'=-y with ODE solver
odesolverreport
class
/************************************************************************* *************************************************************************/ class odesolverreport { ae_int_t nfev; ae_int_t terminationtype; };
odesolverstate
class
/************************************************************************* *************************************************************************/ class odesolverstate { };
odesolverresults
function
/************************************************************************* ODE solver results Called after OdeSolverIteration returned False. INPUT PARAMETERS: State algorithm state (used by OdeSolverIteration). OUTPUT PARAMETERS: M number of tabulated values, M>=1
340 of 430
10/25/2011 03:12 PM
XTbl YTbl Rep array[0..M-1], values of X array[0..M-1,0..N-1], values of Y in X[i] solver report: * Rep.TerminationType completetion code: * -2 X is not ordered by ascending/descending or there are non-distinct X[], i.e. X[i]=X[i+1] * -1 incorrect parameters were specified * 1 task has been solved * Rep.NFEV contains number of function calculations
-- ALGLIB -Copyright 01.09.2009 by Bochkanov Sergey *************************************************************************/ void alglib::odesolverresults( odesolverstate state, ae_int_t& m, real_1d_array& xtbl, real_2d_array& ytbl, odesolverreport& rep); Examples: [1]
odesolverrkck
function
/************************************************************************* Cash-Karp adaptive ODE solver. This subroutine solves ODE Y'=f(Y,x) with initial conditions (here Y may be single variable or vector of N variables). Y(xs)=Ys
INPUT PARAMETERS: Y initial conditions, array[0..N-1]. contains values of Y[] at X[0] N system size X points at which Y should be tabulated, array[0..M-1] integrations starts at X[0], ends at X[M-1], intermediate values at X[i] are returned too. SHOULD BE ORDERED BY ASCENDING OR BY DESCENDING!!!! M number of intermediate points + first point + last point: * M>2 means that you need both Y(X[M-1]) and M-2 values at intermediate points * M=2 means that you want just to integrate from X[0] to X[1] and don't interested in intermediate values. * M=1 means that you don't want to integrate :) it is degenerate case, but it will be handled correctly. * M<1 means error Eps tolerance (absolute/relative error on each step will be less than Eps). When passing: * Eps>0, it means desired ABSOLUTE error * Eps<0, it means desired RELATIVE error. Relative errors are calculated with respect to maximum values of Y seen so far. Be careful to use this criterion when starting from Y[] that are close to zero. H initial step lenth, it will be adjusted automatically after the first step. If H=0, step will be selected automatically (usualy it will be equal to 0.001 of min(x[i]-x[j])). OUTPUT PARAMETERS State structure which stores algorithm state between subsequent calls of OdeSolverIteration. Used for reverse communication. This structure should be passed to the OdeSolverIteration
341 of 430
10/25/2011 03:12 PM
subroutine. SEE ALSO AutoGKSmoothW, AutoGKSingular, AutoGKIteration, AutoGKResults. -- ALGLIB -Copyright 01.09.2009 by Bochkanov Sergey *************************************************************************/ void alglib::odesolverrkck( real_1d_array y, real_1d_array x, double eps, double h, odesolverstate& state); void alglib::odesolverrkck( real_1d_array y, ae_int_t n, real_1d_array x, ae_int_t m, double eps, double h, odesolverstate& state); Examples: [1]
odesolversolve
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 ptr optional pointer which is passed to diff; can be NULL -- ALGLIB -Copyright 01.09.2009 by Bochkanov Sergey *************************************************************************/ void odesolversolve(odesolverstate &state, void (*diff)(const real_1d_array &y, double x, real_1d_array &dy, void *ptr), void *ptr = NULL); Examples: [1]
odesolver_d1 example
#include #include #include #include #include "stdafx.h" <stdlib.h> <stdio.h> <math.h> "diffequations.h"
using namespace alglib; void ode_function_1_diff(const real_1d_array &y, double x, real_1d_array &dy, void *ptr) { // this callback calculates f(y[],x)=-y[0] dy[0] = -y[0]; } int main(int argc, char **argv)
342 of 430
10/25/2011 03:12 PM
{ real_1d_array y = "[1]"; real_1d_array x = "[0, 1, 2, 3]"; double eps = 0.00001; double h = 0; odesolverstate s; ae_int_t m; real_1d_array xtbl; real_2d_array ytbl; odesolverreport rep; odesolverrkck(y, x, eps, h, s); alglib::odesolversolve(s, ode_function_1_diff); odesolverresults(s, m, xtbl, ytbl, rep); printf("%d\n", int(m)); // EXPECTED: 4 printf("%s\n", xtbl.tostring(2).c_str()); // EXPECTED: [0, 1, 2, 3] printf("%s\n", ytbl.tostring(2).c_str()); // EXPECTED: [[1], [0.367], [0.135], [0.050]] return 0; }
ortfac
Functions
subpackage
cmatrixlq cmatrixlqunpackl cmatrixlqunpackq cmatrixqr cmatrixqrunpackq cmatrixqrunpackr hmatrixtd hmatrixtdunpackq rmatrixbd rmatrixbdmultiplybyp rmatrixbdmultiplybyq rmatrixbdunpackdiagonals rmatrixbdunpackpt rmatrixbdunpackq rmatrixhessenberg rmatrixhessenbergunpac kh rmatrixhessenbergunpac kq rmatrixlq rmatrixlqunpackl rmatrixlqunpackq rmatrixqr rmatrixqrunpackq rmatrixqrunpackr smatrixtd smatrixtdunpackq
Examples
cmatrixlq
function
/************************************************************************* LQ decomposition of a rectangular complex matrix of size MxN
343 of 430
10/25/2011 03:12 PM
Input parameters: A matrix A whose indexes range within [0..M-1, 0..N-1] M number of rows in matrix A. N number of columns in matrix A. Output parameters: A matrices Q and L in compact form Tau array of scalar factors which are used to form matrix Q. Array whose indexes range within [0.. Min(M,N)-1] Matrix A is represented as A = LQ, where Q is an orthogonal matrix of size MxM, L - lower triangular (or lower trapezoid) matrix of size MxN. -- 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 *************************************************************************/ void alglib::cmatrixlq( complex_2d_array& a, ae_int_t m, ae_int_t n, complex_1d_array& tau);
cmatrixlqunpackl
function
/************************************************************************* Unpacking of matrix L from the LQ decomposition of a matrix A Input parameters: A matrices Q and L in compact form. Output of CMatrixLQ subroutine. M number of rows in given matrix A. M>=0. N number of columns in given matrix A. N>=0. Output parameters: L matrix L, array[0..M-1, 0..N-1]. -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixlqunpackl( complex_2d_array a, ae_int_t m, ae_int_t n, complex_2d_array& l);
cmatrixlqunpackq
function
/************************************************************************* Partial unpacking of matrix Q from LQ decomposition of a complex matrix A. Input parameters: A M N Tau matrices Q and R in compact form. Output of CMatrixLQ subroutine . number of rows in matrix A. M>=0. number of columns in matrix A. N>=0. scalar factors which are used to form Q.
344 of 430
10/25/2011 03:12 PM
Output of CMatrixLQ subroutine . required number of rows in matrix Q. N>=QColumns>=0. first QRows rows of matrix Q. Array whose index ranges within [0..QRows-1, 0..N-1]. If QRows=0, array isn't changed.
QRows
Output parameters: Q -
-- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixlqunpackq( complex_2d_array a, ae_int_t m, ae_int_t n, complex_1d_array tau, ae_int_t qrows, complex_2d_array& q);
cmatrixqr
function
/************************************************************************* QR decomposition of a rectangular complex matrix of size MxN Input parameters: A matrix A whose indexes range within [0..M-1, 0..N-1] M number of rows in matrix A. N number of columns in matrix A. Output parameters: A matrices Q and R in compact form Tau array of scalar factors which are used to form matrix Q. Array whose indexes range within [0.. Min(M,N)-1] Matrix A is represented as A = QR, where Q is an orthogonal matrix of size MxM, R - upper triangular (or upper trapezoid) matrix of size MxN. -- 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 *************************************************************************/ void alglib::cmatrixqr( complex_2d_array& a, ae_int_t m, ae_int_t n, complex_1d_array& tau);
cmatrixqrunpackq
function
/************************************************************************* Partial unpacking of matrix Q from QR decomposition of a complex matrix A. Input parameters: A M N Tau matrices Q and R in compact form. Output of CMatrixQR subroutine . number of rows in matrix A. M>=0. number of columns in matrix A. N>=0. scalar factors which are used to form Q.
345 of 430
10/25/2011 03:12 PM
Output of CMatrixQR subroutine . required number of columns in matrix Q. M>=QColumns>=0. first QColumns columns of matrix Q. Array whose index ranges within [0..M-1, 0..QColumns-1]. If QColumns=0, array isn't changed.
QColumns
-- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixqrunpackq( complex_2d_array a, ae_int_t m, ae_int_t n, complex_1d_array tau, ae_int_t qcolumns, complex_2d_array& q);
cmatrixqrunpackr
function
/************************************************************************* Unpacking of matrix R from the QR decomposition of a matrix A Input parameters: A matrices Q and R in compact form. Output of CMatrixQR subroutine. M number of rows in given matrix A. M>=0. N number of columns in given matrix A. N>=0. Output parameters: R matrix R, array[0..M-1, 0..N-1]. -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixqrunpackr( complex_2d_array a, ae_int_t m, ae_int_t n, complex_2d_array& r);
hmatrixtd
function
/************************************************************************* Reduction of a Hermitian matrix which is given by its higher or lower triangular part to a real tridiagonal matrix using unitary similarity transformation: Q'*A*Q = T. Input parameters: A matrix to be transformed array with elements [0..N-1, 0..N-1]. N size of matrix A. IsUpper storage format. If IsUpper = True, then matrix A is given by its upper triangle, and the lower triangle is not used and not modified by the algorithm, and vice versa if IsUpper = False.
346 of 430
10/25/2011 03:12 PM
Output parameters: A matrices T and Q in compact form (see lower) Tau array of factors which are forming matrices H(i) array with elements [0..N-2]. D main diagonal of real symmetric matrix T. array with elements [0..N-1]. E secondary diagonal of real symmetric matrix T. array with elements [0..N-2]. If IsUpper=True, the matrix Q is represented as a product of elementary reflectors Q = H(n-2) . . . H(2) H(0). Each H(i) has the form H(i) = I - tau * v * v' where tau is a complex scalar, and v is a complex vector with v(i+1:n-1) = 0, v(i) = 1, v(0:i-1) is stored on exit in A(0:i-1,i+1), and tau in TAU(i). If IsUpper=False, the matrix Q is represented as a product of elementary reflectors Q = H(0) H(2) . . . H(n-2). Each H(i) has the form H(i) = I - tau * v * v' where tau is a complex scalar, and v is a complex vector with v(0:i) = 0, v(i+1) = 1, v(i+2:n-1) is stored on exit in A(i+2:n-1,i), and tau in TAU(i). The contents of A on exit are illustrated by the following examples with n = 5: if UPLO = 'U': ( ( ( ( ( d e d v1 e d v2 v2 e d v3 v3 v3 e d ) ) ) ) ) if UPLO = 'L': ( ( ( ( ( d e v0 v0 v0 d e v1 v1 ) ) ) ) )
d e v2
d e
where d and e denote diagonal and off-diagonal elements of T, and vi denotes an element of the vector defining H(i). -- LAPACK routine (version 3.0) -Univ. of Tennessee, Univ. of California Berkeley, NAG Ltd., Courant Institute, Argonne National Lab, and Rice University October 31, 1992 *************************************************************************/ void alglib::hmatrixtd( complex_2d_array& a, ae_int_t n, bool isupper, complex_1d_array& tau, real_1d_array& d, real_1d_array& e);
347 of 430
10/25/2011 03:12 PM
hmatrixtdunpackq
function
/************************************************************************* Unpacking matrix Q which reduces a Hermitian matrix to a real tridiagonal form. Input parameters: A the result of a HMatrixTD subroutine N size of matrix A. IsUpper storage format (a parameter of HMatrixTD subroutine) Tau the result of a HMatrixTD subroutine Output parameters: Q transformation matrix. array with elements [0..N-1, 0..N-1]. -- ALGLIB -Copyright 2005-2010 by Bochkanov Sergey *************************************************************************/ void alglib::hmatrixtdunpackq( complex_2d_array a, ae_int_t n, bool isupper, complex_1d_array tau, complex_2d_array& q);
rmatrixbd
function
/************************************************************************* Reduction of a rectangular matrix to bidiagonal form The algorithm reduces the rectangular matrix A to orthogonal transformations P and Q: A = Q*B*P. bidiagonal form by
Input parameters: A source matrix. array[0..M-1, 0..N-1] M number of rows in matrix A. N number of columns in matrix A. Output parameters: A matrices Q, B, P in compact form (see below). TauQ scalar factors which are used to form matrix Q. TauP scalar factors which are used to form matrix P. The main diagonal and one of the secondary diagonals of matrix A are replaced with bidiagonal matrix B. Other elements contain elementary reflections which form MxM matrix Q and NxN matrix P, respectively. If M>=N, B is the upper bidiagonal MxN matrix and is stored in the corresponding elements of matrix A. Matrix Q is represented as a product of elementary reflections Q = H(0)*H(1)*...*H(n-1), where H(i) = 1-tau*v*v'. Here tau is a scalar which is stored in TauQ[i], and vector v has the following structure: v(0:i-1)=0, v(i)=1, v(i+1:m-1) is stored in elements A(i+1:m-1,i). Matrix P is as follows: P = G(0)*G(1)*...*G(n-2), where G(i) = 1 - tau*u*u'. Tau is stored in TauP[i], u(0:i)=0, u(i+1)=1, u(i+2:n-1) is stored in elements A(i,i+2:n-1). If M<N, B is the lower bidiagonal MxN matrix and is stored in the corresponding elements of matrix A. Q = H(0)*H(1)*...*H(m-2), where H(i) = 1 - tau*v*v', tau is stored in TauQ, v(0:i)=0, v(i+1)=1, v(i+2:m-1) is stored in elements A(i+2:m-1,i). P = G(0)*G(1)*...*G(m-1),
348 of 430
10/25/2011 03:12 PM
G(i) = 1-tau*u*u', tau is stored in is stored in A(i,i+1:n-1). EXAMPLE: m=6, n=5 (m > n): ( ( ( ( ( ( d v1 v1 v1 v1 v1 e d v2 v2 v2 v2 u1 e d v3 v3 v3 u1 u2 e d v4 v4 u1 u2 u3 e d v5 ) ) ) ) ) ) m=5, n=6 (m < n): ( ( ( ( ( d e v1 v1 v1 u1 d e v2 v2 u1 u2 d e v3 u1 u2 u3 d e u1 u2 u3 u4 d u1 u2 u3 u4 u5 ) ) ) ) ) TauP, u(0:i-1)=0, u(i)=1, u(i+1:n-1)
Here vi and ui are vectors which form H(i) and G(i), and d and e are the diagonal and off-diagonal elements of matrix B. -- 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. Sergey Bochkanov, ALGLIB project, translation from FORTRAN to pseudocode, 2007-2010. *************************************************************************/ void alglib::rmatrixbd( real_2d_array& a, ae_int_t m, ae_int_t n, real_1d_array& tauq, real_1d_array& taup);
rmatrixbdmultiplybyp
function
/************************************************************************* Multiplication by matrix P which reduces matrix A to bidiagonal form. The algorithm allows pre- or post-multiply by P or P'. Input parameters: QP M N TAUP Z ZRows ZColumns matrices Q and P in compact form. Output of RMatrixBD subroutine. number of rows in matrix A. number of columns in matrix A. scalar factors which are used to form P. Output of RMatrixBD subroutine. multiplied matrix. Array whose indexes range within [0..ZRows-1,0..ZColumns-1]. number of rows in matrix Z. If FromTheRight=False, ZRows=N, otherwise ZRows can be arbitrary. number of columns in matrix Z. If FromTheRight=True, ZColumns=N, otherwise ZColumns can be arbitrary. pre- or post-multiply. multiply by P or P'.
FromTheRight DoTranspose -
Output parameters: Z - product of Z and P. Array whose indexes range within [0..ZRows-1,0..ZColumns-1]. If ZRows=0 or ZColumns=0, the array is not modified. -- ALGLIB -2005-2010 Bochkanov Sergey
349 of 430
10/25/2011 03:12 PM
*************************************************************************/ void alglib::rmatrixbdmultiplybyp( real_2d_array qp, ae_int_t m, ae_int_t n, real_1d_array taup, real_2d_array& z, ae_int_t zrows, ae_int_t zcolumns, bool fromtheright, bool dotranspose);
rmatrixbdmultiplybyq
function
/************************************************************************* Multiplication by matrix Q which reduces matrix A to bidiagonal form. The algorithm allows pre- or post-multiply by Q or Q'. Input parameters: QP M N TAUQ Z ZRows ZColumns matrices Q and P in compact form. Output of ToBidiagonal subroutine. number of rows in matrix A. number of columns in matrix A. scalar factors which are used to form Q. Output of ToBidiagonal subroutine. multiplied matrix. array[0..ZRows-1,0..ZColumns-1] number of rows in matrix Z. If FromTheRight=False, ZRows=M, otherwise ZRows can be arbitrary. number of columns in matrix Z. If FromTheRight=True, ZColumns=M, otherwise ZColumns can be arbitrary. pre- or post-multiply. multiply by Q or Q'. product of Z and Q. Array[0..ZRows-1,0..ZColumns-1] If ZRows=0 or ZColumns=0, the array is not modified.
FromTheRight DoTranspose Output parameters: Z -
-- ALGLIB -2005-2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixbdmultiplybyq( real_2d_array qp, ae_int_t m, ae_int_t n, real_1d_array tauq, real_2d_array& z, ae_int_t zrows, ae_int_t zcolumns, bool fromtheright, bool dotranspose);
rmatrixbdunpackdiagonals
function
/************************************************************************* Unpacking of the main and secondary diagonals of bidiagonal decomposition of matrix A.
350 of 430
10/25/2011 03:12 PM
Input parameters: B output of RMatrixBD subroutine. M number of rows in matrix B. N number of columns in matrix B. Output parameters: IsUpper True, if the matrix is upper bidiagonal. otherwise IsUpper is False. D the main diagonal. Array whose index ranges within [0..Min(M,N)-1]. E the secondary diagonal (upper or lower, depending on the value of IsUpper). Array index ranges within [0..Min(M,N)-1], the last element is not used. -- ALGLIB -2005-2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixbdunpackdiagonals( real_2d_array b, ae_int_t m, ae_int_t n, bool& isupper, real_1d_array& d, real_1d_array& e);
rmatrixbdunpackpt
function
/************************************************************************* Unpacking matrix P which reduces matrix A to bidiagonal form. The subroutine returns transposed matrix P. Input parameters: QP matrices Q and P in compact form. Output of ToBidiagonal subroutine. M number of rows in matrix A. N number of columns in matrix A. TAUP scalar factors which are used to form P. Output of ToBidiagonal subroutine. PTRows required number of rows of matrix P^T. N >= PTRows >= 0. Output parameters: PT first PTRows columns of matrix P^T Array[0..PTRows-1, 0..N-1] If PTRows=0, the array is not modified. -- ALGLIB -2005-2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixbdunpackpt( real_2d_array qp, ae_int_t m, ae_int_t n, real_1d_array taup, ae_int_t ptrows, real_2d_array& pt);
351 of 430
10/25/2011 03:12 PM
rmatrixbdunpackq
function
/************************************************************************* Unpacking matrix Q which reduces a matrix to bidiagonal form. Input parameters: QP M N TAUQ QColumns matrices Q and P in compact form. Output of ToBidiagonal subroutine. number of rows in matrix A. number of columns in matrix A. scalar factors which are used to form Q. Output of ToBidiagonal subroutine. required number of columns in matrix Q. M>=QColumns>=0. first QColumns columns of matrix Q. Array[0..M-1, 0..QColumns-1] If QColumns=0, the array is not modified.
-- ALGLIB -2005-2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixbdunpackq( real_2d_array qp, ae_int_t m, ae_int_t n, real_1d_array tauq, ae_int_t qcolumns, real_2d_array& q);
rmatrixhessenberg
function
/************************************************************************* Reduction of a square matrix to upper Hessenberg form: Q'*A*Q = H, where Q is an orthogonal matrix, H - Hessenberg matrix. Input parameters: A matrix A with elements [0..N-1, 0..N-1] N size of matrix A. Output parameters: A matrices Q and P in compact form (see below). Tau array of scalar factors which are used to form matrix Q. Array whose index ranges within [0..N-2] Matrix H is located on the main diagonal, on the lower secondary diagonal and above the main diagonal of matrix A. The elements which are used to form matrix Q are situated in array Tau and below the lower secondary diagonal of matrix A as follows: Matrix Q is represented as a product of elementary reflections Q = H(0)*H(2)*...*H(n-2), where each H(i) is given by H(i) = 1 - tau * v * (v^T) where tau is a scalar stored in Tau[I]; v - is a real vector,
352 of 430
10/25/2011 03:12 PM
so that v(0:i) = 0, v(i+1) = 1, v(i+2:n-1) stored in A(i+2:n-1,i). -- LAPACK routine (version 3.0) -Univ. of Tennessee, Univ. of California Berkeley, NAG Ltd., Courant Institute, Argonne National Lab, and Rice University October 31, 1992 *************************************************************************/ void alglib::rmatrixhessenberg( real_2d_array& a, ae_int_t n, real_1d_array& tau);
rmatrixhessenbergunpackh
function
/************************************************************************* Unpacking matrix H (the result of matrix A reduction to upper Hessenberg form) Input parameters: A output of RMatrixHessenberg subroutine. N size of matrix A. Output parameters: H matrix H. Array whose indexes range within [0..N-1, 0..N-1]. -- ALGLIB -2005-2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixhessenbergunpackh( real_2d_array a, ae_int_t n, real_2d_array& h);
rmatrixhessenbergunpackq
function
/************************************************************************* Unpacking matrix Q which reduces matrix A to upper Hessenberg form Input parameters: A output of RMatrixHessenberg subroutine. N size of matrix A. Tau scalar factors which are used to form Q. Output of RMatrixHessenberg subroutine. Output parameters: Q matrix Q. Array whose indexes range within [0..N-1, 0..N-1]. -- ALGLIB -2005-2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixhessenbergunpackq( real_2d_array a, ae_int_t n, real_1d_array tau, real_2d_array& q);
353 of 430
10/25/2011 03:12 PM
rmatrixlq
function
/************************************************************************* LQ decomposition of a rectangular matrix of size MxN Input parameters: A matrix A whose indexes range within [0..M-1, 0..N-1]. M number of rows in matrix A. N number of columns in matrix A. Output parameters: A matrices L and Q in compact form (see below) Tau array of scalar factors which are used to form matrix Q. Array whose index ranges within [0..Min(M,N)-1]. Matrix A is represented as A = LQ, where Q is an orthogonal matrix of size MxM, L - lower triangular (or lower trapezoid) matrix of size M x N. The elements of matrix L are located on and below the main diagonal of matrix A. The elements which are located in Tau array and above the main diagonal of matrix A are used to form matrix Q as follows: Matrix Q is represented as a product of elementary reflections Q = H(k-1)*H(k-2)*...*H(1)*H(0), where k = min(m,n), and each H(i) is of the form H(i) = 1 - tau * v * (v^T) where tau is a scalar stored in Tau[I]; v - real vector, so that v(0:i-1)=0, v(i) = 1, v(i+1:n-1) stored in A(i,i+1:n-1). -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixlq( real_2d_array& a, ae_int_t m, ae_int_t n, real_1d_array& tau);
rmatrixlqunpackl
function
/************************************************************************* Unpacking of matrix L from the LQ decomposition of a matrix A Input parameters: A matrices Q and L in compact form. Output of RMatrixLQ subroutine. M number of rows in given matrix A. M>=0. N number of columns in given matrix A. N>=0. Output parameters: L matrix L, array[0..M-1, 0..N-1]. -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/
354 of 430
10/25/2011 03:12 PM
void alglib::rmatrixlqunpackl( real_2d_array a, ae_int_t m, ae_int_t n, real_2d_array& l);
rmatrixlqunpackq
function
/************************************************************************* Partial unpacking of matrix Q from the LQ decomposition of a matrix A Input parameters: A matrices L and Q in compact form. Output of RMatrixLQ subroutine. M number of rows in given matrix A. M>=0. N number of columns in given matrix A. N>=0. Tau scalar factors which are used to form Q. Output of the RMatrixLQ subroutine. QRows required number of rows in matrix Q. N>=QRows>=0. Output parameters: Q first QRows rows of matrix Q. Array whose indexes range within [0..QRows-1, 0..N-1]. If QRows=0, the array remains unchanged. -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixlqunpackq( real_2d_array a, ae_int_t m, ae_int_t n, real_1d_array tau, ae_int_t qrows, real_2d_array& q);
rmatrixqr
function
/************************************************************************* QR decomposition of a rectangular matrix of size MxN Input parameters: A matrix A whose indexes range within [0..M-1, 0..N-1]. M number of rows in matrix A. N number of columns in matrix A. Output parameters: A matrices Q and R in compact form (see below). Tau array of scalar factors which are used to form matrix Q. Array whose index ranges within [0.. Min(M-1,N-1)]. Matrix A is represented as A = QR, where Q is an orthogonal matrix of size MxM, R - upper triangular (or upper trapezoid) matrix of size M x N. The elements of matrix R are located on and above the main diagonal of matrix A. The elements which are located in Tau array and below the main diagonal of matrix A are used to form matrix Q as follows: Matrix Q is represented as a product of elementary reflections
355 of 430
10/25/2011 03:12 PM
Q = H(0)*H(2)*...*H(k-1), where k = min(m,n), and each H(i) is in the form H(i) = 1 - tau * v * (v^T) where tau is a scalar stored in Tau[I]; v - real vector, so that v(0:i-1) = 0, v(i) = 1, v(i+1:m-1) stored in A(i+1:m-1,i). -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixqr( real_2d_array& a, ae_int_t m, ae_int_t n, real_1d_array& tau);
rmatrixqrunpackq
function
/************************************************************************* Partial unpacking of matrix Q from the QR decomposition of a matrix A Input parameters: A matrices Q and R in compact form. Output of RMatrixQR subroutine. M number of rows in given matrix A. M>=0. N number of columns in given matrix A. N>=0. Tau scalar factors which are used to form Q. Output of the RMatrixQR subroutine. QColumns - required number of columns of matrix Q. M>=QColumns>=0. Output parameters: Q first QColumns columns of matrix Q. Array whose indexes range within [0..M-1, 0..QColumns-1]. If QColumns=0, the array remains unchanged. -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixqrunpackq( real_2d_array a, ae_int_t m, ae_int_t n, real_1d_array tau, ae_int_t qcolumns, real_2d_array& q);
rmatrixqrunpackr
function
/************************************************************************* Unpacking of matrix R from the QR decomposition of a matrix A Input parameters: A matrices Q and R in compact form. Output of RMatrixQR subroutine. M number of rows in given matrix A. M>=0.
356 of 430
10/25/2011 03:12 PM
N number of columns in given matrix A. N>=0.
Output parameters: R matrix R, array[0..M-1, 0..N-1]. -- ALGLIB routine -17.02.2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixqrunpackr( real_2d_array a, ae_int_t m, ae_int_t n, real_2d_array& r);
smatrixtd
function
/************************************************************************* Reduction of a symmetric matrix which is given by its higher or lower triangular part to a tridiagonal matrix using orthogonal similarity transformation: Q'*A*Q=T. Input parameters: A matrix to be transformed array with elements [0..N-1, 0..N-1]. N size of matrix A. IsUpper storage format. If IsUpper = True, then matrix A is given by its upper triangle, and the lower triangle is not used and not modified by the algorithm, and vice versa if IsUpper = False. Output parameters: A matrices T and Q in compact form (see lower) Tau array of factors which are forming matrices H(i) array with elements [0..N-2]. D main diagonal of symmetric matrix T. array with elements [0..N-1]. E secondary diagonal of symmetric matrix T. array with elements [0..N-2]. If IsUpper=True, the matrix Q is represented as a product of elementary reflectors Q = H(n-2) . . . H(2) H(0). Each H(i) has the form H(i) = I - tau * v * v' where tau is a real scalar, and v is a real vector with v(i+1:n-1) = 0, v(i) = 1, v(0:i-1) is stored on exit in A(0:i-1,i+1), and tau in TAU(i). If IsUpper=False, the matrix Q is represented as a product of elementary reflectors Q = H(0) H(2) . . . H(n-2). Each H(i) has the form H(i) = I - tau * v * v'
357 of 430
10/25/2011 03:12 PM
where tau is a real scalar, and v is a real vector with v(0:i) = 0, v(i+1) = 1, v(i+2:n-1) is stored on exit in A(i+2:n-1,i), and tau in TAU(i). The contents of A on exit are illustrated by the following examples with n = 5: if UPLO = 'U': ( ( ( ( ( d e d v1 e d v2 v2 e d v3 v3 v3 e d ) ) ) ) ) if UPLO = 'L': ( ( ( ( ( d e v0 v0 v0 d e v1 v1 ) ) ) ) )
d e v2
d e
where d and e denote diagonal and off-diagonal elements of T, and vi denotes an element of the vector defining H(i). -- LAPACK routine (version 3.0) -Univ. of Tennessee, Univ. of California Berkeley, NAG Ltd., Courant Institute, Argonne National Lab, and Rice University October 31, 1992 *************************************************************************/ void alglib::smatrixtd( real_2d_array& a, ae_int_t n, bool isupper, real_1d_array& tau, real_1d_array& d, real_1d_array& e);
smatrixtdunpackq
function
/************************************************************************* Unpacking matrix Q which reduces symmetric matrix to a tridiagonal form. Input parameters: A the result of a SMatrixTD subroutine N size of matrix A. IsUpper storage format (a parameter of SMatrixTD subroutine) Tau the result of a SMatrixTD subroutine Output parameters: Q transformation matrix. array with elements [0..N-1, 0..N-1]. -- ALGLIB -Copyright 2005-2010 by Bochkanov Sergey *************************************************************************/ void alglib::smatrixtdunpackq( real_2d_array a, ae_int_t n, bool isupper, real_1d_array tau, real_2d_array& q);
pca
subpackage
10/25/2011 03:12 PM
358 of 430
Functions
pcabuildbasis
Examples
pcabuildbasis
function
/************************************************************************* Principal components analysis Subroutine builds orthogonal basis where first axis corresponds to direction with maximum variance, second axis maximizes variance in subspace orthogonal to first axis and so on. It should be noted that, unlike LDA, PCA does not use class labels. INPUT PARAMETERS: X NPoints NVars dataset, array[0..NPoints-1,0..NVars-1]. matrix contains ONLY INDEPENDENT VARIABLES. dataset size, NPoints>=0 number of independent variables, NVars>=1
: Info return code: * -4, if SVD subroutine haven't converged * -1, if wrong parameters has been passed (NPoints<0, NVars<1) * 1, if task is solved S2 array[0..NVars-1]. variance values corresponding to basis vectors. V array[0..NVars-1,0..NVars-1] matrix, whose columns store basis vectors. -- ALGLIB -Copyright 25.08.2008 by Bochkanov Sergey *************************************************************************/ void alglib::pcabuildbasis( real_2d_array x, ae_int_t npoints, ae_int_t nvars, ae_int_t& info, real_1d_array& s2, real_2d_array& v);
poissondistr
Functions
invpoissondistribution poissoncdistribution poissondistribution
subpackage
Examples
359 of 430
10/25/2011 03:12 PM
invpoissondistribution
function
/************************************************************************* Inverse Poisson distribution Finds the Poisson variable x such that the integral from 0 to x of the Poisson density is equal to the given probability y. This is accomplished using the inverse gamma integral function and the relation m = igami( k+1, y ). ACCURACY: See inverse incomplete gamma function Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::invpoissondistribution(ae_int_t k, double y);
poissoncdistribution
function
/************************************************************************* Complemented Poisson distribution Returns the sum of the terms k+1 to infinity of the Poisson distribution: inf. --m > e -j=k+1 j m -j!
The terms are not summed directly; instead the incomplete gamma integral is employed, according to the formula y = pdtrc( k, m ) = igam( k+1, m ). The arguments must both be positive. ACCURACY: See incomplete gamma function Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::poissoncdistribution(ae_int_t k, double m);
poissondistribution
function
/************************************************************************* Poisson distribution Returns the sum of the first k+1 terms of the Poisson
360 of 430
10/25/2011 03:12 PM
distribution: k -> -j=0 -m e j m -j!
The terms are not summed directly; instead the incomplete gamma integral is employed, according to the relation y = pdtr( k, m ) = igamc( k+1, m ). The arguments must both be positive. ACCURACY: See incomplete gamma function Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::poissondistribution(ae_int_t k, double m);
polint
Functions
subpackage
polynomialbar2cheb polynomialbar2pow polynomialbuild polynomialbuildc heb1 polynomialbuildc heb2 polynomialbuildeqdist polynomialcalccheb1 polynomialcalccheb2 polynomialcalceqdist polynomialcheb2bar polynomialpow2bar
Examples
polint_d_calcdiff polint_d_conv polint_d_spec Interpolation and differentiation using baryc entric representation Conversion between power basis and baryc entric representation Polynomial interpolation on spec ial grids (equidistant, Chebyshev I/II)
polynomialbar2cheb
function
/************************************************************************* Conversion from barycentric representation to Chebyshev basis. This function has O(N^2) complexity. INPUT PARAMETERS: P polynomial in barycentric form A,B base interval for Chebyshev polynomials (see below) A<>B OUTPUT PARAMETERS T coefficients of Chebyshev representation;
361 of 430
10/25/2011 03:12 PM
P(x) = sum { T[i]*Ti(2*(x-A)/(B-A)-1), i=0..N-1 }, where Ti - I-th Chebyshev polynomial. NOTES: barycentric interpolant passed as P may be either polynomial obtained from polynomial interpolation/ fitting or rational function which is NOT polynomial. We can't distinguish between these two cases, and this algorithm just tries to work assuming that P IS a polynomial. If not, algorithm will return results, but they won't have any meaning. -- ALGLIB -Copyright 30.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialbar2cheb( barycentricinterpolant p, double a, double b, real_1d_array& t);
polynomialbar2pow
function
/************************************************************************* Conversion from barycentric representation to power basis. This function has O(N^2) complexity. INPUT PARAMETERS: P polynomial in barycentric form C offset (see below); 0.0 is used as default value. S scale (see below); 1.0 is used as default value. S<>0. OUTPUT PARAMETERS A coefficients, P(x) = sum { A[i]*((X-C)/S)î, i=0..N-1 } N number of coefficients (polynomial degree plus 1) NOTES: 1. this function accepts offset and scale, which can be set to improve numerical properties of polynomial. For example, if P was obtained as result of interpolation on [-1,+1], you can set C=0 and S=1 and represent P as sum of 1, x, x^2, x^3 and so on. In most cases you it is exactly what you need. However, if your interpolation model was built on [999,1001], you will see significant growth of numerical errors when using {1, x, x^2, x^3} as basis. Representing P as sum of 1, (x-1000), (x-1000)^2, (x-1000)^3 will be better option. Such representation can be obtained by using 1000.0 as offset C and 1.0 as scale S. 2. power basis is ill-conditioned and tricks described above can't solve this problem completely. This function will return coefficients in any case, but for N>8 they will become unreliable. However, N's less than 5 are pretty safe. barycentric interpolant passed as P may be either polynomial obtained from polynomial interpolation/ fitting or rational function which is NOT polynomial. We can't distinguish between these two cases, and this algorithm just tries to work assuming that P IS a polynomial. If not, algorithm will return results, but they won't have any meaning.
3.
-- ALGLIB -Copyright 30.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialbar2pow(
362 of 430
10/25/2011 03:12 PM
barycentricinterpolant p, real_1d_array& a); void alglib::polynomialbar2pow( barycentricinterpolant p, double c, double s, real_1d_array& a); Examples: [1]
polynomialbuild
function
/************************************************************************* Lagrange intepolant: generation of the model on the general grid. This function has O(N^2) complexity. INPUT PARAMETERS: X abscissas, array[0..N-1] Y function values, array[0..N-1] N number of points, N>=1 OUTPUT PARAMETERS P barycentric model which represents Lagrange interpolant (see ratint unit info and BarycentricCalc() description for more information). -- ALGLIB -Copyright 02.12.2009 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialbuild( real_1d_array x, real_1d_array y, barycentricinterpolant& p); void alglib::polynomialbuild( real_1d_array x, real_1d_array y, ae_int_t n, barycentricinterpolant& p); Examples: [1]
polynomialbuildcheb1
function
/************************************************************************* Lagrange intepolant on Chebyshev grid (first kind). This function has O(N) complexity. INPUT PARAMETERS: A left boundary of [A,B] B right boundary of [A,B] Y function values at the nodes, array[0..N-1], Y[I] = Y(0.5*(B+A) + 0.5*(B-A)*Cos(PI*(2*i+1)/(2*n))) N number of points, N>=1 for N=1 a constant model is constructed. OUTPUT PARAMETERS P barycentric model which represents Lagrange interpolant (see ratint unit info and BarycentricCalc() description for more information).
363 of 430
10/25/2011 03:12 PM
-- ALGLIB -Copyright 03.12.2009 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialbuildcheb1( double a, double b, real_1d_array y, barycentricinterpolant& p); void alglib::polynomialbuildcheb1( double a, double b, real_1d_array y, ae_int_t n, barycentricinterpolant& p); Examples: [1]
polynomialbuildcheb2
function
/************************************************************************* Lagrange intepolant on Chebyshev grid (second kind). This function has O(N) complexity. INPUT PARAMETERS: A left boundary of [A,B] B right boundary of [A,B] Y function values at the nodes, array[0..N-1], Y[I] = Y(0.5*(B+A) + 0.5*(B-A)*Cos(PI*i/(n-1))) N number of points, N>=1 for N=1 a constant model is constructed. OUTPUT PARAMETERS P barycentric model which represents Lagrange interpolant (see ratint unit info and BarycentricCalc() description for more information). -- ALGLIB -Copyright 03.12.2009 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialbuildcheb2( double a, double b, real_1d_array y, barycentricinterpolant& p); void alglib::polynomialbuildcheb2( double a, double b, real_1d_array y, ae_int_t n, barycentricinterpolant& p); Examples: [1]
polynomialbuildeqdist
function
/************************************************************************* Lagrange intepolant: generation of the model on equidistant grid. This function has O(N) complexity. INPUT PARAMETERS:
364 of 430
10/25/2011 03:12 PM
A B Y N left boundary of [A,B] right boundary of [A,B] function values at the nodes, array[0..N-1] number of points, N>=1 for N=1 a constant model is constructed.
OUTPUT PARAMETERS P barycentric model which represents Lagrange interpolant (see ratint unit info and BarycentricCalc() description for more information). -- ALGLIB -Copyright 03.12.2009 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialbuildeqdist( double a, double b, real_1d_array y, barycentricinterpolant& p); void alglib::polynomialbuildeqdist( double a, double b, real_1d_array y, ae_int_t n, barycentricinterpolant& p); Examples: [1]
polynomialcalccheb1
function
/************************************************************************* Fast polynomial interpolation function on Chebyshev points (first kind) with O(N) complexity. INPUT PARAMETERS: A left boundary of [A,B] B right boundary of [A,B] F function values, array[0..N-1] N number of points on Chebyshev grid (first kind), X[i] = 0.5*(B+A) + 0.5*(B-A)*Cos(PI*(2*i+1)/(2*n)) for N=1 a constant model is constructed. T position where P(x) is calculated RESULT value of the Lagrange interpolant at T IMPORTANT this function provides fast interface which is not overflow-safe nor it is very precise. the best option is to use PolIntBuildCheb1()/BarycentricCalc() subroutines unless you are pretty sure that your data will not result in overflow. -- ALGLIB -Copyright 02.12.2009 by Bochkanov Sergey *************************************************************************/ double alglib::polynomialcalccheb1( double a, double b, real_1d_array f, double t); double alglib::polynomialcalccheb1(
365 of 430
10/25/2011 03:12 PM
double a, double b, real_1d_array f, ae_int_t n, double t); Examples: [1]
polynomialcalccheb2
function
/************************************************************************* Fast polynomial interpolation function on Chebyshev points (second kind) with O(N) complexity. INPUT PARAMETERS: A left boundary of [A,B] B right boundary of [A,B] F function values, array[0..N-1] N number of points on Chebyshev grid (second kind), X[i] = 0.5*(B+A) + 0.5*(B-A)*Cos(PI*i/(n-1)) for N=1 a constant model is constructed. T position where P(x) is calculated RESULT value of the Lagrange interpolant at T IMPORTANT this function provides fast interface which is not overflow-safe nor it is very precise. the best option is to use PolIntBuildCheb2()/BarycentricCalc() subroutines unless you are pretty sure that your data will not result in overflow. -- ALGLIB -Copyright 02.12.2009 by Bochkanov Sergey *************************************************************************/ double alglib::polynomialcalccheb2( double a, double b, real_1d_array f, double t); double alglib::polynomialcalccheb2( double a, double b, real_1d_array f, ae_int_t n, double t); Examples: [1]
polynomialcalceqdist
function
/************************************************************************* Fast equidistant polynomial interpolation function with O(N) complexity INPUT PARAMETERS: A left boundary of [A,B] B right boundary of [A,B] F function values, array[0..N-1] N number of points on equidistant grid, N>=1
366 of 430
10/25/2011 03:12 PM
for N=1 a constant model is constructed. position where P(x) is calculated
RESULT value of the Lagrange interpolant at T IMPORTANT this function provides fast interface which is not overflow-safe nor it is very precise. the best option is to use PolynomialBuildEqDist()/BarycentricCalc() subroutines unless you are pretty sure that your data will not result in overflow. -- ALGLIB -Copyright 02.12.2009 by Bochkanov Sergey *************************************************************************/ double alglib::polynomialcalceqdist( double a, double b, real_1d_array f, double t); double alglib::polynomialcalceqdist( double a, double b, real_1d_array f, ae_int_t n, double t); Examples: [1]
polynomialcheb2bar
function
/************************************************************************* Conversion from Chebyshev basis to barycentric representation. This function has O(N^2) complexity. INPUT PARAMETERS: T coefficients of Chebyshev representation; P(x) = sum { T[i]*Ti(2*(x-A)/(B-A)-1), i=0..N }, where Ti - I-th Chebyshev polynomial. N number of coefficients: * if given, only leading N elements of T are used * if not given, automatically determined from size of T A,B base interval for Chebyshev polynomials (see above) A<B OUTPUT PARAMETERS P polynomial in barycentric form -- ALGLIB -Copyright 30.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialcheb2bar( real_1d_array t, double a, double b, barycentricinterpolant& p); void alglib::polynomialcheb2bar( real_1d_array t, ae_int_t n, double a, double b,
367 of 430
10/25/2011 03:12 PM
barycentricinterpolant& p);
polynomialpow2bar
function
/************************************************************************* Conversion from power basis to barycentric representation. This function has O(N^2) complexity. INPUT PARAMETERS: A coefficients, P(x) = sum { A[i]*((X-C)/S)î, i=0..N-1 } N number of coefficients (polynomial degree plus 1) * if given, only leading N elements of A are used * if not given, automatically determined from size of A C offset (see below); 0.0 is used as default value. S scale (see below); 1.0 is used as default value. S<>0. OUTPUT PARAMETERS P polynomial in barycentric form NOTES: 1. this function accepts offset and scale, which can be set to improve numerical properties of polynomial. For example, if you interpolate on [-1,+1], you can set C=0 and S=1 and convert from sum of 1, x, x^2, x^3 and so on. In most cases you it is exactly what you need. However, if your interpolation model was built on [999,1001], you will see significant growth of numerical errors when using {1, x, x^2, x^3} as input basis. Converting from sum of 1, (x-1000), (x-1000)^2, (x-1000)^3 will be better option (you have to specify 1000.0 as offset C and 1.0 as scale S). 2. power basis is ill-conditioned and tricks described above can't solve this problem completely. This function will return barycentric model in any case, but for N>8 accuracy well degrade. However, N's less than 5 are pretty safe.
-- ALGLIB -Copyright 30.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::polynomialpow2bar( real_1d_array a, barycentricinterpolant& p); void alglib::polynomialpow2bar( real_1d_array a, ae_int_t n, double c, double s, barycentricinterpolant& p); Examples: [1]
polint_d_calcdiff example
368 of 430
10/25/2011 03:12 PM
using namespace alglib; int main(int argc, char **argv) { // // Here we demonstrate polynomial interpolation and differentiation // of y=x^2-x sampled at [0,1,2]. Barycentric representation of polynomial is used. // real_1d_array x = "[0,1,2]"; real_1d_array y = "[0,0,2]"; double t = -1; double v; double dv; double d2v; barycentricinterpolant p; // barycentric model is created polynomialbuild(x, y, p); // barycentric interpolation is demonstrated v = barycentriccalc(p, t); printf("%.4f\n", double(v)); // EXPECTED: 2.0 // barycentric differentation is demonstrated barycentricdiff1(p, t, v, dv); printf("%.4f\n", double(v)); // EXPECTED: 2.0 printf("%.4f\n", double(dv)); // EXPECTED: -3.0 // second derivatives with barycentric representation barycentricdiff1(p, t, v, dv); printf("%.4f\n", double(v)); // EXPECTED: 2.0 printf("%.4f\n", double(dv)); // EXPECTED: -3.0 barycentricdiff2(p, t, v, dv, d2v); printf("%.4f\n", double(v)); // EXPECTED: 2.0 printf("%.4f\n", double(dv)); // EXPECTED: -3.0 printf("%.4f\n", double(d2v)); // EXPECTED: 2.0 return 0; }
polint_d_conv example
using namespace alglib; int main(int argc, char **argv) { // // Here we demonstrate conversion of y=x^2-x // between power basis and barycentric representation. // real_1d_array a = "[0,-1,+1]"; double t = 2; real_1d_array a2; double v;
369 of 430
10/25/2011 03:12 PM
barycentricinterpolant p; // // a=[0,-1,+1] is decomposition of y=x^2-x in the power basis: // // y = 0 - 1*x + 1*x^2 // // We convert it to the barycentric form. // polynomialpow2bar(a, p); // now we have barycentric interpolation; we can use it for interpolation v = barycentriccalc(p, t); printf("%.2f\n", double(v)); // EXPECTED: 2.0 // we can also convert back from barycentric representation to power basis polynomialbar2pow(p, a2); printf("%s\n", a2.tostring(2).c_str()); // EXPECTED: [0,-1,+1] return 0; }
polint_d_spec example
using namespace alglib; int main(int argc, char **argv) { // // Temporaries: // * values of y=x^2-x sampled at three special grids: // * equdistant grid spanning [0,2], x[i] = 2*i/(N-1), i=0..N-1 // * Chebyshev-I grid spanning [-1,+1], x[i] = 1 + Cos(PI*(2*i+1)/(2*n)), i=0..N-1 // * Chebyshev-II grid spanning [-1,+1], x[i] = 1 + Cos(PI*i/(n-1)), i=0..N-1 // * barycentric interpolants for these three grids // * vectors to store coefficients of quadratic representation // real_1d_array y_eqdist = "[0,0,2]"; real_1d_array y_cheb1 = "[-0.116025,0.000000,1.616025]"; real_1d_array y_cheb2 = "[0,0,2]"; barycentricinterpolant p_eqdist; barycentricinterpolant p_cheb1; barycentricinterpolant p_cheb2; real_1d_array a_eqdist; real_1d_array a_cheb1; real_1d_array a_cheb2; // // First, we demonstrate construction of barycentric interpolants on // special grids. We unpack power representation to ensure that // interpolant was built correctly. // // In all three cases we should get same quadratic function. // polynomialbuildeqdist(0.0, 2.0, y_eqdist, p_eqdist);
370 of 430
10/25/2011 03:12 PM
polynomialbar2pow(p_eqdist, a_eqdist); printf("%s\n", a_eqdist.tostring(4).c_str()); // EXPECTED: [0,-1,+1] polynomialbuildcheb1(-1, +1, y_cheb1, p_cheb1); polynomialbar2pow(p_cheb1, a_cheb1); printf("%s\n", a_cheb1.tostring(4).c_str()); // EXPECTED: [0,-1,+1] polynomialbuildcheb2(-1, +1, y_cheb2, p_cheb2); polynomialbar2pow(p_cheb2, a_cheb2); printf("%s\n", a_cheb2.tostring(4).c_str()); // EXPECTED: [0,-1,+1] // // Now we demonstrate polynomial interpolation without construction // of the barycentricinterpolant structure. // // We calculate interpolant value at x=-2. // In all three cases we should get same f=6 // double t = -2; double v; v = polynomialcalceqdist(0.0, 2.0, y_eqdist, t); printf("%.4f\n", double(v)); // EXPECTED: 6.0 v = polynomialcalccheb1(-1, +1, y_cheb1, t); printf("%.4f\n", double(v)); // EXPECTED: 6.0 v = polynomialcalccheb2(-1, +1, y_cheb2, t); printf("%.4f\n", double(v)); // EXPECTED: 6.0 return 0; }
psif
subpackage
Functions
psi
Examples
psi
function
/************************************************************************* Psi (digamma) function psi(x) = d -- ln | (x) dx
is the logarithmic derivative of the gamma function. For integer x, n-1 psi(n) = -EUL + > 1/k. k=1 This formula is used for 0 < n <= 10. If x is negative, it
371 of 430
10/25/2011 03:12 PM
is transformed to a positive argument by the reflection formula psi(1-x) = psi(x) + pi cot(pi x). For general positive x, the argument is made greater than 10 using the recurrence psi(x+1) = psi(x) + 1/x. Then the following asymptotic expansion is applied: inf. B 2k > ------2k k=1 2k x
psi(x) = log(x) - 1/2x -
where the B2k are Bernoulli numbers. ACCURACY: Relative error (except absolute when |psi| < 1): arithmetic domain # trials peak rms IEEE 0,30 30000 1.3e-15 1.4e-16 IEEE -30,0 40000 1.5e-15 2.2e-16 Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1992, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::psi(double x);
pspline
Classes
subpackage
pspline2interpolant pspline3interpolant
Functions
pspline2arclength pspline2build pspline2buildperiodic pspline2calc pspline2diff pspline2diff2 pspline2parametervalues pspline2tangent pspline3arclength pspline3build pspline3buildperiodic pspline3calc pspline3diff pspline3diff2 pspline3parametervalues pspline3tangent
Examples
pspline2interpolant
class
/*************************************************************************
372 of 430
10/25/2011 03:12 PM
Parametric spline inteprolant: 2-dimensional curve. You should not try to access its members directly - use PSpline2XXXXXXXX() functions instead. *************************************************************************/ class pspline2interpolant { };
pspline3interpolant
class
/************************************************************************* Parametric spline inteprolant: 3-dimensional curve. You should not try to access its members directly - use PSpline3XXXXXXXX() functions instead. *************************************************************************/ class pspline3interpolant { };
pspline2arclength
function
/************************************************************************* This function calculates arc length, i.e. length of curve between t=a and t=b. INPUT PARAMETERS: P parametric spline interpolant A,B parameter values corresponding to arc ends: * B>A will result in positive length returned * B<A will result in negative length returned RESULT: length of arc starting at T=A and ending at T=B. -- ALGLIB PROJECT -Copyright 30.05.2010 by Bochkanov Sergey *************************************************************************/ double alglib::pspline2arclength( pspline2interpolant p, double a, double b);
pspline2build
function
/************************************************************************* This function builds non-periodic 2-dimensional parametric spline which starts at (X[0],Y[0]) and ends at (X[N-1],Y[N-1]). INPUT PARAMETERS: XY points, array[0..N-1,0..1]. XY[I,0:1] corresponds to the Ith point. Order of points is important! N points count, N>=5 for Akima splines, N>=2 for other types splines. ST spline type:
of
373 of 430
10/25/2011 03:12 PM
* 0 Akima spline * 1 parabolically terminated Catmull-Rom spline (Tension=0) * 2 parabolically terminated cubic spline parameterization type: * 0 uniform * 1 chord length * 2 centripetal
PT
OUTPUT PARAMETERS: P parametric spline interpolant NOTES: * this function assumes that there all consequent points are distinct. I.e. (x0,y0)<>(x1,y1), (x1,y1)<>(x2,y2), (x2,y2)<>(x3,y3) and so on. However, non-consequent points may coincide, i.e. we can have (x0,y0)= =(x2,y2). -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline2build( real_2d_array xy, ae_int_t n, ae_int_t st, ae_int_t pt, pspline2interpolant& p);
pspline2buildperiodic
function
/************************************************************************* This function builds periodic 2-dimensional parametric spline which starts at (X[0],Y[0]), goes through all points to (X[N-1],Y[N-1]) and then back to (X[0],Y[0]). INPUT PARAMETERS: XY points, array[0..N-1,0..1]. XY[I,0:1] corresponds to the Ith point. XY[N-1,0:1] must be different from XY[0,0:1]. Order of points is important! N points count, N>=3 for other types of splines. ST spline type: * 1 Catmull-Rom spline (Tension=0) with cyclic boundary conditions * 2 cubic spline with cyclic boundary conditions PT parameterization type: * 0 uniform * 1 chord length * 2 centripetal OUTPUT PARAMETERS: P parametric spline interpolant NOTES: * this function assumes that there all consequent points are distinct. I.e. (x0,y0)<>(x1,y1), (x1,y1)<>(x2,y2), (x2,y2)<>(x3,y3) and so on. However, non-consequent points may coincide, i.e. we can have (x0,y0)= =(x2,y2). * last point of sequence is NOT equal to the first point. You shouldn't make curve "explicitly periodic" by making them equal. -- ALGLIB PROJECT --
374 of 430
10/25/2011 03:12 PM
Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline2buildperiodic( real_2d_array xy, ae_int_t n, ae_int_t st, ae_int_t pt, pspline2interpolant& p);
pspline2calc
function
/************************************************************************* This function calculates the value of the parametric spline for a given value of parameter T INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-position Y Y-position -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline2calc( pspline2interpolant p, double t, double& x, double& y);
pspline2diff
function
/************************************************************************* This function calculates derivative, i.e. it returns (dX/dT,dY/dT). INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-value DX X-derivative Y Y-value DY Y-derivative -- ALGLIB PROJECT --
375 of 430
10/25/2011 03:12 PM
Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline2diff( pspline2interpolant p, double t, double& x, double& dx, double& y, double& dy);
pspline2diff2
function
/************************************************************************* This function calculates first and second derivative with respect to T. INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-value DX derivative D2X second derivative Y Y-value DY derivative D2Y second derivative -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline2diff2( pspline2interpolant p, double t, double& x, double& dx, double& d2x, double& y, double& dy, double& d2y);
pspline2parametervalues
function
/************************************************************************* This function returns vector of parameter values correspoding to points. I.e. for P created from (X[0],Y[0])...(X[N-1],Y[N-1]) and U=TValues(P) have (X[0],Y[0]) = PSpline2Calc(P,U[0]), (X[1],Y[1]) = PSpline2Calc(P,U[1]), (X[2],Y[2]) = PSpline2Calc(P,U[2]), ... INPUT PARAMETERS: P parametric spline interpolant we
376 of 430
10/25/2011 03:12 PM
OUTPUT PARAMETERS: N array size T array[0..N-1] NOTES: * for non-periodic splines U[0]=0, U[0]<U[1]<...<U[N-1], U[N-1]=1 * for periodic splines U[0]=0, U[0]<U[1]<...<U[N-1], U[N-1]<1 -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline2parametervalues( pspline2interpolant p, ae_int_t& n, real_1d_array& t);
pspline2tangent
function
/************************************************************************* This function calculates tangent vector for a given value of parameter T INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-component of tangent vector (normalized) Y Y-component of tangent vector (normalized) NOTE: X^2+Y^2 is either 1 (for non-zero tangent vector) or 0. -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline2tangent( pspline2interpolant p, double t, double& x, double& y);
pspline3arclength
function
/************************************************************************* This function calculates arc length, i.e. length of curve between t=a and t=b. INPUT PARAMETERS: P parametric spline interpolant A,B parameter values corresponding to arc ends: * B>A will result in positive length returned * B<A will result in negative length returned
377 of 430
10/25/2011 03:12 PM
RESULT: length of arc starting at T=A and ending at T=B. -- ALGLIB PROJECT -Copyright 30.05.2010 by Bochkanov Sergey *************************************************************************/ double alglib::pspline3arclength( pspline3interpolant p, double a, double b);
pspline3build
function
/************************************************************************* This function builds non-periodic 3-dimensional parametric spline which starts at (X[0],Y[0],Z[0]) and ends at (X[N-1],Y[N-1],Z[N-1]). Same as PSpline2Build() function, but for 3D, so we description here. won't duplicate its
-- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline3build( real_2d_array xy, ae_int_t n, ae_int_t st, ae_int_t pt, pspline3interpolant& p);
pspline3buildperiodic
function
/************************************************************************* This function builds periodic 3-dimensional parametric spline which starts at (X[0],Y[0],Z[0]), goes through all points to (X[N-1],Y[N-1],Z[N-1]) and then back to (X[0],Y[0],Z[0]). Same as PSpline2Build() function, but for 3D, so we description here. won't duplicate its
-- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline3buildperiodic( real_2d_array xy, ae_int_t n, ae_int_t st, ae_int_t pt, pspline3interpolant& p);
pspline3calc
function
/************************************************************************* This function calculates the value of the parametric spline for a given value of parameter T.
378 of 430
10/25/2011 03:12 PM
INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-position Y Y-position Z Z-position -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline3calc( pspline3interpolant p, double t, double& x, double& y, double& z);
pspline3diff
function
/************************************************************************* This function calculates derivative, i.e. it returns (dX/dT,dY/dT,dZ/dT). INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-value DX X-derivative Y Y-value DY Y-derivative Z Z-value DZ Z-derivative -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline3diff( pspline3interpolant p, double t, double& x, double& dx, double& y, double& dy, double& z, double& dz);
379 of 430
10/25/2011 03:12 PM
pspline3diff2
function
/************************************************************************* This function calculates first and second derivative with respect to T. INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-value DX derivative D2X second derivative Y Y-value DY derivative D2Y second derivative Z Z-value DZ derivative D2Z second derivative -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline3diff2( pspline3interpolant p, double t, double& x, double& dx, double& d2x, double& y, double& dy, double& d2y, double& z, double& dz, double& d2z);
pspline3parametervalues
function
/************************************************************************* This function returns vector of parameter values correspoding to points. Same as PSpline2ParameterValues(), but for 3D. -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline3parametervalues( pspline3interpolant p, ae_int_t& n, real_1d_array& t);
pspline3tangent
function
380 of 430
10/25/2011 03:12 PM
/************************************************************************* This function calculates tangent vector for a given value of parameter T INPUT PARAMETERS: P parametric spline interpolant T point: * T in [0,1] corresponds to interval spanned by points * for non-periodic splines T<0 (or T>1) correspond to parts of the curve before the first (after the last) point * for periodic splines T<0 (or T>1) are projected into [0,1] by making T=T-floor(T). OUTPUT PARAMETERS: X X-component of tangent vector (normalized) Y Y-component of tangent vector (normalized) Z Z-component of tangent vector (normalized) NOTE: X^2+Y^2+Z^2 is either 1 (for non-zero tangent vector) or 0. -- ALGLIB PROJECT -Copyright 28.05.2010 by Bochkanov Sergey *************************************************************************/ void alglib::pspline3tangent( pspline3interpolant p, double t, double& x, double& y, double& z);
ratint
Classes
subpackage
barycentricinterpolant
Functions
barycentricbuildfloaterhormann barycentricbuildxyw barycentriccalc barycentricdiff1 barycentricdiff2 barycentriclintransx barycentriclintransy barycentricunpac k
Examples
barycentricinterpolant
class
/************************************************************************* Barycentric interpolant. *************************************************************************/ class barycentricinterpolant {
381 of 430
10/25/2011 03:12 PM
};
barycentricbuildfloaterhormann
function
/************************************************************************* Rational interpolant without poles The subroutine constructs the rational interpolating function without real poles (see 'Barycentric rational interpolation with no poles and high rates of approximation', Michael S. Floater. and Kai Hormann, for more information on this subject). Input parameters: X interpolation nodes, array[0..N-1]. Y function values, array[0..N-1]. N number of nodes, N>0. D order of the interpolation scheme, 0 <= D <= N-1. D<0 will cause an error. D>=N it will be replaced with D=N-1. if you don't know what D to choose, use small value about 3-5. Output parameters: B barycentric interpolant. Note: this algorithm always succeeds and calculates the weights to machine precision. with close
-- ALGLIB PROJECT -Copyright 17.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::barycentricbuildfloaterhormann( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t d, barycentricinterpolant& b);
barycentricbuildxyw
function
/************************************************************************* Rational interpolant from X/Y/W arrays F(t) = SUM(i=0,n-1,w[i]*f[i]/(t-x[i])) / SUM(i=0,n-1,w[i]/(t-x[i])) INPUT PARAMETERS: X interpolation nodes, array[0..N-1] F function values, array[0..N-1] W barycentric weights, array[0..N-1] N nodes count, N>0 OUTPUT PARAMETERS: B barycentric interpolant built from (X, Y, W) -- ALGLIB -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::barycentricbuildxyw( real_1d_array x, real_1d_array y,
382 of 430
10/25/2011 03:12 PM
real_1d_array w, ae_int_t n, barycentricinterpolant& b);
barycentriccalc
function
/************************************************************************* Rational interpolation using barycentric formula F(t) = SUM(i=0,n-1,w[i]*f[i]/(t-x[i])) / SUM(i=0,n-1,w[i]/(t-x[i])) Input parameters: B barycentric interpolant built with one of model building subroutines. T interpolation point Result: barycentric interpolant F(t) -- ALGLIB -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ double alglib::barycentriccalc(barycentricinterpolant b, double t);
barycentricdiff1
function
/************************************************************************* Differentiation of barycentric interpolant: first derivative. Algorithm used in this subroutine is very robust and should not fail until provided with values too close to MaxRealNumber (usually MaxRealNumber/N or greater will overflow). INPUT PARAMETERS: B barycentric interpolant built with one of model building subroutines. T interpolation point OUTPUT PARAMETERS: F barycentric interpolant at T DF first derivative NOTE -- ALGLIB -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::barycentricdiff1( barycentricinterpolant b, double t, double& f, double& df);
barycentricdiff2
function
/************************************************************************* Differentiation of barycentric interpolant: first/second derivatives.
383 of 430
10/25/2011 03:12 PM
INPUT PARAMETERS: B barycentric interpolant built with one of model building subroutines. T interpolation point OUTPUT PARAMETERS: F barycentric interpolant at T DF first derivative D2F second derivative NOTE: this algorithm may fail due to overflow/underflor if used on data whose values are close to MaxRealNumber or MinRealNumber. Use more robust BarycentricDiff1() subroutine in such cases. -- ALGLIB -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::barycentricdiff2( barycentricinterpolant b, double t, double& f, double& df, double& d2f);
barycentriclintransx
function
/************************************************************************* This subroutine performs linear transformation of the argument. INPUT PARAMETERS: B rational interpolant in barycentric form CA, CB transformation coefficients: x = CA*t + CB OUTPUT PARAMETERS: B transformed interpolant with X replaced by T -- ALGLIB PROJECT -Copyright 19.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::barycentriclintransx( barycentricinterpolant b, double ca, double cb);
barycentriclintransy
function
/************************************************************************* This subroutine performs linear transformation of the barycentric interpolant. INPUT PARAMETERS: B rational interpolant in barycentric form CA, CB transformation coefficients: B2(x) = CA*B(x) + CB OUTPUT PARAMETERS: B transformed interpolant -- ALGLIB PROJECT --
384 of 430
10/25/2011 03:12 PM
Copyright 19.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::barycentriclintransy( barycentricinterpolant b, double ca, double cb);
barycentricunpack
function
/************************************************************************* Extracts X/Y/W arrays from rational interpolant INPUT PARAMETERS: B barycentric interpolant OUTPUT PARAMETERS: N nodes count, N>0 X interpolation nodes, array[0..N-1] F function values, array[0..N-1] W barycentric weights, array[0..N-1] -- ALGLIB -Copyright 17.08.2009 by Bochkanov Sergey *************************************************************************/ void alglib::barycentricunpack( barycentricinterpolant b, ae_int_t& n, real_1d_array& x, real_1d_array& y, real_1d_array& w);
rcond
subpackage
Functions
cmatrixlurcond1 cmatrixlurcondinf cmatrixrcond1 cmatrixrcondinf cmatrixtrrcond1 cmatrixtrrcondinf hpdmatrixcholeskyrc ond hpdmatrixrcond rmatrixlurcond1 rmatrixlurcondinf rmatrixrcond1 rmatrixrcondinf rmatrixtrrcond1 rmatrixtrrcondinf spdmatrixcholeskyrc ond spdmatrixrcond
Examples
cmatrixlurcond1
function
10/25/2011 03:12 PM
385 of 430
/************************************************************************* Estimate of the condition number of a matrix given by its LU decomposition (1-norm) The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: LUA N LU decomposition of a matrix in compact form. Output of the CMatrixLU subroutine. size of matrix A.
Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::cmatrixlurcond1(complex_2d_array lua, ae_int_t n);
cmatrixlurcondinf
function
/************************************************************************* Estimate of the condition number of a matrix given by its LU decomposition (infinity norm). The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: LUA LU decomposition of a matrix in compact form. Output of the CMatrixLU subroutine. N size of matrix A. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::cmatrixlurcondinf(complex_2d_array lua, ae_int_t n);
cmatrixrcond1
function
/************************************************************************* Estimate of a matrix condition number (1-norm) The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array whose indexes range within [0..N-1, 0..N-1]. N size of matrix A. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF,
386 of 430
10/25/2011 03:12 PM
0.0 is returned in such cases. *************************************************************************/ double alglib::cmatrixrcond1(complex_2d_array a, ae_int_t n);
cmatrixrcondinf
function
/************************************************************************* Estimate of a matrix condition number (infinity-norm). The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array whose indexes range within [0..N-1, 0..N-1]. N size of matrix A. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::cmatrixrcondinf(complex_2d_array a, ae_int_t n);
cmatrixtrrcond1
function
/************************************************************************* Triangular matrix: estimate of a condition number (1-norm) The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array[0..N-1, 0..N-1]. N size of A. IsUpper True, if the matrix is upper triangular. IsUnit True, if the matrix has a unit diagonal. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::cmatrixtrrcond1( complex_2d_array a, ae_int_t n, bool isupper, bool isunit);
cmatrixtrrcondinf
function
/************************************************************************* Triangular matrix: estimate of a matrix condition number (infinity-norm). The algorithm calculates a lower bound of the condition number. In this case,
387 of 430
10/25/2011 03:12 PM
the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array whose indexes range within [0..N-1, 0..N-1]. N size of matrix A. IsUpper True, if the matrix is upper triangular. IsUnit True, if the matrix has a unit diagonal. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::cmatrixtrrcondinf( complex_2d_array a, ae_int_t n, bool isupper, bool isunit);
hpdmatrixcholeskyrcond
function
/************************************************************************* Condition number estimate of a Hermitian positive definite matrix given by Cholesky decomposition. The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). It should be noted that 1-norm and inf-norm condition numbers of symmetric matrices are equal, so the algorithm doesn't take into account the differences between these types of norms. Input parameters: CD - Cholesky decomposition of matrix A, output of SMatrixCholesky subroutine. N - size of matrix A. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::hpdmatrixcholeskyrcond( complex_2d_array a, ae_int_t n, bool isupper);
hpdmatrixrcond
function
/************************************************************************* Condition number estimate of a Hermitian positive definite matrix. The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix).
388 of 430
10/25/2011 03:12 PM
It should be noted that 1-norm and inf-norm of condition numbers of symmetric matrices are equal, so the algorithm doesn't take into account the differences between these types of norms. Input parameters: A Hermitian positive definite matrix which is given by its upper or lower triangle depending on the value of IsUpper. Array with elements [0..N-1, 0..N-1]. N size of matrix A. IsUpper storage format. Result: 1/LowerBound(cond(A)), if matrix A is positive definite, -1, if matrix A is not positive definite, and its condition number could not be found by this algorithm. NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::hpdmatrixrcond( complex_2d_array a, ae_int_t n, bool isupper);
rmatrixlurcond1
function
/************************************************************************* Estimate of the condition number of a matrix given by its LU decomposition (1-norm) The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: LUA N LU decomposition of a matrix in compact form. Output of the RMatrixLU subroutine. size of matrix A.
Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::rmatrixlurcond1(real_2d_array lua, ae_int_t n);
rmatrixlurcondinf
function
/************************************************************************* Estimate of the condition number of a matrix given by its LU decomposition (infinity norm). The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: LUA LU decomposition of a matrix in compact form. Output of the RMatrixLU subroutine.
389 of 430
10/25/2011 03:12 PM
N size of matrix A.
Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::rmatrixlurcondinf(real_2d_array lua, ae_int_t n);
rmatrixrcond1
function
/************************************************************************* Estimate of a matrix condition number (1-norm) The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array whose indexes range within [0..N-1, 0..N-1]. N size of matrix A. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::rmatrixrcond1(real_2d_array a, ae_int_t n);
rmatrixrcondinf
function
/************************************************************************* Estimate of a matrix condition number (infinity-norm). The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array whose indexes range within [0..N-1, 0..N-1]. N size of matrix A. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::rmatrixrcondinf(real_2d_array a, ae_int_t n);
rmatrixtrrcond1
function
/************************************************************************* Triangular matrix: estimate of a condition number (1-norm) The algorithm calculates a lower bound of the condition number. In this case,
390 of 430
10/25/2011 03:12 PM
the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array[0..N-1, 0..N-1]. N size of A. IsUpper True, if the matrix is upper triangular. IsUnit True, if the matrix has a unit diagonal. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::rmatrixtrrcond1( real_2d_array a, ae_int_t n, bool isupper, bool isunit);
rmatrixtrrcondinf
function
/************************************************************************* Triangular matrix: estimate of a matrix condition number (infinity-norm). The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). Input parameters: A matrix. Array whose indexes range within [0..N-1, 0..N-1]. N size of matrix A. IsUpper True, if the matrix is upper triangular. IsUnit True, if the matrix has a unit diagonal. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::rmatrixtrrcondinf( real_2d_array a, ae_int_t n, bool isupper, bool isunit);
spdmatrixcholeskyrcond
function
/************************************************************************* Condition number estimate of a symmetric positive definite matrix given by Cholesky decomposition. The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). It should be noted that 1-norm and inf-norm condition numbers of symmetric matrices are equal, so the algorithm doesn't take into account the
391 of 430
10/25/2011 03:12 PM
differences between these types of norms. Input parameters: CD - Cholesky decomposition of matrix A, output of SMatrixCholesky subroutine. N - size of matrix A. Result: 1/LowerBound(cond(A)) NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::spdmatrixcholeskyrcond( real_2d_array a, ae_int_t n, bool isupper);
spdmatrixrcond
function
/************************************************************************* Condition number estimate of a symmetric positive definite matrix. The algorithm calculates a lower bound of the condition number. In this case, the algorithm does not return a lower bound of the condition number, but an inverse number (to avoid an overflow in case of a singular matrix). It should be noted that 1-norm and inf-norm of condition numbers of symmetric matrices are equal, so the algorithm doesn't take into account the differences between these types of norms. Input parameters: A symmetric positive definite matrix which is given by its upper or lower triangle depending on the value of IsUpper. Array with elements [0..N-1, 0..N-1]. N size of matrix A. IsUpper storage format. Result: 1/LowerBound(cond(A)), if matrix A is positive definite, -1, if matrix A is not positive definite, and its condition number could not be found by this algorithm. NOTE: if k(A) is very large, then matrix is assumed degenerate, k(A)=INF, 0.0 is returned in such cases. *************************************************************************/ double alglib::spdmatrixrcond(real_2d_array a, ae_int_t n, bool isupper);
schur
subpackage
Functions
rmatrixschur
Examples
392 of 430
10/25/2011 03:12 PM
rmatrixschur
function
/************************************************************************* Subroutine performing the Schur decomposition of a general matrix by using the QR algorithm with multiple shifts. The source matrix A is represented as S'*A*S = T, where S is an orthogonal matrix (Schur vectors), T - upper quasi-triangular matrix (with blocks of sizes 1x1 and 2x2 on the main diagonal). Input parameters: A matrix to be decomposed. Array whose indexes range within [0..N-1, 0..N-1]. N size of A, N>=0. Output parameters: A contains matrix T. Array whose indexes range within [0..N-1, 0..N-1]. S contains Schur vectors. Array whose indexes range within [0..N-1, 0..N-1]. Note 1: The block structure of matrix T can be easily recognized: since all the elements below the blocks are zeros, the elements a[i+1,i] which are equal to 0 show the block border. 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 in linear algebra). If you require maximum performance on your machine, it is recommended to adjust this parameter manually. Result: True, if the algorithm has converged and parameters A and S contain the result. False, if the algorithm has not converged. Algorithm implemented on the basis of the DHSEQR subroutine (LAPACK 3.0 library). *************************************************************************/ bool alglib::rmatrixschur(real_2d_array& a, ae_int_t n, real_2d_array& s);
spdgevd
Functions
subpackage
smatrixgevd smatrixgevdreduc e
Examples
smatrixgevd
function
/************************************************************************* Algorithm for solving the following generalized symmetric positive-definite
393 of 430
10/25/2011 03:12 PM
eigenproblem: A*x = lambda*B*x (1) or A*B*x = lambda*x (2) or B*A*x = lambda*x (3). where A is a symmetric matrix, B - symmetric positive-definite matrix. The problem is solved by reducing it to an ordinary symmetric eigenvalue problem. Input parameters: A N IsUpperA B IsUpperB ZNeeded symmetric matrix which is given by its upper or lower triangular part. Array whose indexes range within [0..N-1, 0..N-1]. size of matrices A and B. storage format of matrix A. symmetric positive-definite matrix which is given by its upper or lower triangular part. Array whose indexes range within [0..N-1, 0..N-1]. storage format of matrix B. if ZNeeded is equal to: * 0, the eigenvectors are not returned; * 1, the eigenvectors are returned. if ProblemType is equal to: * 1, the following problem is solved: A*x = lambda*B*x; * 2, the following problem is solved: A*B*x = lambda*x; * 3, the following problem is solved: B*A*x = lambda*x. eigenvalues in ascending order. Array whose index ranges within [0..N-1]. if ZNeeded is equal to: * 0, Z hasnt changed; * 1, Z contains eigenvectors. Array whose indexes range within [0..N-1, 0..N-1]. The eigenvectors are stored in matrix columns. It should be noted that the eigenvectors in such problems do not form an orthogonal system.
ProblemType -
Output parameters: D Z -
Result: True, if the problem was solved successfully. False, if the error occurred during the Cholesky decomposition of matrix B (the matrix isnt positive-definite) or during the work of the iterative algorithm for solving the symmetric eigenproblem. See also the GeneralizedSymmetricDefiniteEVDReduce subroutine. -- ALGLIB -Copyright 1.28.2006 by Bochkanov Sergey *************************************************************************/ bool alglib::smatrixgevd( real_2d_array a, ae_int_t n, bool isuppera, real_2d_array b, bool isupperb, ae_int_t zneeded, ae_int_t problemtype, real_1d_array& d, real_2d_array& z);
smatrixgevdreduce
function
/*************************************************************************
394 of 430
10/25/2011 03:12 PM
Algorithm for reduction of the following generalized symmetric positivedefinite eigenvalue problem: A*x = lambda*B*x (1) or A*B*x = lambda*x (2) or B*A*x = lambda*x (3) to the symmetric eigenvalues problem C*y = lambda*y (eigenvalues of this and the given problems are the same, and the eigenvectors of the given problem could be obtained by multiplying the obtained eigenvectors by the transformation matrix x = R*y). Here A is a symmetric matrix, B - symmetric positive-definite matrix. Input parameters: A N IsUpperA B symmetric matrix which is given by its upper or lower triangular part. Array whose indexes range within [0..N-1, 0..N-1]. size of matrices A and B. storage format of matrix A. symmetric positive-definite matrix which is given by its upper or lower triangular part. Array whose indexes range within [0..N-1, 0..N-1]. storage format of matrix B. if ProblemType is equal to: * 1, the following problem is solved: A*x = lambda*B*x; * 2, the following problem is solved: A*B*x = lambda*x; * 3, the following problem is solved: B*A*x = lambda*x. symmetric matrix which is given by its upper or lower triangle depending on IsUpperA. Contains matrix C. Array whose indexes range within [0..N-1, 0..N-1]. upper triangular or low triangular transformation matrix which is used to obtain the eigenvectors of a given problem as the product of eigenvectors of C (from the right) and matrix R (from the left). If the matrix is upper triangular, the elements below the main diagonal are equal to 0 (and vice versa). Thus, we can perform the multiplication without taking into account the internal structure (which is an easier though less effective way). Array whose indexes range within [0..N-1, 0..N-1]. type of matrix R (upper or lower triangular).
IsUpperB ProblemType -
Output parameters: A R -
IsUpperR
Result: True, if the problem was reduced successfully. False, if the error occurred during the Cholesky decomposition of matrix B (the matrix is not positive-definite). -- ALGLIB -Copyright 1.28.2006 by Bochkanov Sergey *************************************************************************/ bool alglib::smatrixgevdreduce( real_2d_array& a, ae_int_t n, bool isuppera, real_2d_array b, bool isupperb, ae_int_t problemtype, real_2d_array& r, bool& isupperr);
spline1d
395 of 430
subpackage
10/25/2011 03:12 PM
Classes
spline1dinterpolant
Functions
spline1dbuildakima spline1dbuildcatmullrom spline1dbuildcubic spline1dbuildhermite spline1dbuildlinear spline1dcalc spline1dconvcubic spline1dconvdiff2c ubic spline1dconvdiffc ubic spline1ddiff spline1dgriddiff2c ubic spline1dgriddiffcubic spline1dintegrate spline1dlintransx spline1dlintransy spline1dunpack
Examples
spline1d_d_convdiff spline1d_d_cubic spline1d_d_griddiff spline1d_d_linear Resampling using c ubic splines Cubic spline interpolation Differentiation on the grid using c ubic splines Piec ewise linear spline interpolation
spline1dinterpolant
class
/************************************************************************* 1-dimensional spline inteprolant *************************************************************************/ class spline1dinterpolant { };
spline1dbuildakima
function
/************************************************************************* This subroutine builds Akima spline interpolant INPUT PARAMETERS: X Y N spline nodes, array[0..N-1] function values, array[0..N-1] points count (optional): * N>=5 * if given, only first N points are used to build spline * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) spline interpolant
OUTPUT PARAMETERS: C -
396 of 430
10/25/2011 03:12 PM
ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. -- ALGLIB PROJECT -Copyright 24.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dbuildakima( real_1d_array x, real_1d_array y, spline1dinterpolant& c); void alglib::spline1dbuildakima( real_1d_array x, real_1d_array y, ae_int_t n, spline1dinterpolant& c);
spline1dbuildcatmullrom
function
/************************************************************************* This subroutine builds Catmull-Rom spline interpolant. INPUT PARAMETERS: X Y spline nodes, array[0..N-1]. function values, array[0..N-1].
OPTIONAL PARAMETERS: N points count: * N>=2 * if given, only first N points are used to build spline * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) BoundType boundary condition type: * -1 for periodic boundary condition * 0 for parabolically terminated spline (default) Tension tension parameter: * tension=0 corresponds to classic Catmull-Rom spline (default) * 0<tension<1 corresponds to more general form - cardinal spline OUTPUT PARAMETERS: C ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. PROBLEMS WITH PERIODIC BOUNDARY CONDITIONS: Problems with periodic boundary conditions have Y[first_point]=Y[last_point]. However, this subroutine doesn't require you to specify equal values for the first and last points - it automatically forces them to be equal by copying Y[first_point] (corresponds to the leftmost, minimal X[]) to Y[last_point]. However it is recommended to pass consistent values of Y[], i.e. to make Y[first_point]=Y[last_point]. -- ALGLIB PROJECT -Copyright 23.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dbuildcatmullrom( real_1d_array x, real_1d_array y, spline interpolant
397 of 430
10/25/2011 03:12 PM
spline1dinterpolant& c); void alglib::spline1dbuildcatmullrom( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t boundtype, double tension, spline1dinterpolant& c);
spline1dbuildcubic
function
/************************************************************************* This subroutine builds cubic spline interpolant. INPUT PARAMETERS: X Y spline nodes, array[0..N-1]. function values, array[0..N-1].
OPTIONAL PARAMETERS: N points count: * N>=2 * if given, only first N points are used to build spline * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) BoundLType boundary condition type for the left boundary BoundL left boundary condition (first or second derivative, depending on the BoundLType) BoundRType boundary condition type for the right boundary BoundR right boundary condition (first or second derivative, depending on the BoundRType) OUTPUT PARAMETERS: C ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. SETTING BOUNDARY VALUES: The BoundLType/BoundRType parameters can have the following values: * -1, which corresonds to the periodic (cyclic) boundary conditions. In this case: * both BoundLType and BoundRType must be equal to -1. * BoundL/BoundR are ignored * Y[last] is ignored (it is assumed to be equal to Y[first]). * 0, which corresponds to the parabolically terminated spline (BoundL and/or BoundR are ignored). * 1, which corresponds to the first derivative boundary condition * 2, which corresponds to the second derivative boundary condition * by default, BoundType=0 is used PROBLEMS WITH PERIODIC BOUNDARY CONDITIONS: Problems with periodic boundary conditions have Y[first_point]=Y[last_point]. However, this subroutine doesn't require you to specify equal values for the first and last points - it automatically forces them to be equal by copying Y[first_point] (corresponds to the leftmost, minimal X[]) to Y[last_point]. However it is recommended to pass consistent values of Y[], i.e. to make Y[first_point]=Y[last_point]. -- ALGLIB PROJECT -spline interpolant
398 of 430
10/25/2011 03:12 PM
Copyright 23.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dbuildcubic( real_1d_array x, real_1d_array y, spline1dinterpolant& c); void alglib::spline1dbuildcubic( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t boundltype, double boundl, ae_int_t boundrtype, double boundr, spline1dinterpolant& c);
spline1dbuildhermite
function
/************************************************************************* This subroutine builds Hermite spline interpolant. INPUT PARAMETERS: X Y D N spline nodes, array[0..N-1] function values, array[0..N-1] derivatives, array[0..N-1] points count (optional): * N>=2 * if given, only first N points are used to build spline * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) spline interpolant.
OUTPUT PARAMETERS: C ORDER OF POINTS
Subroutine automatically sorts points, so caller may pass unsorted array. -- ALGLIB PROJECT -Copyright 23.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dbuildhermite( real_1d_array x, real_1d_array y, real_1d_array d, spline1dinterpolant& c); void alglib::spline1dbuildhermite( real_1d_array x, real_1d_array y, real_1d_array d, ae_int_t n, spline1dinterpolant& c);
spline1dbuildlinear
function
/************************************************************************* This subroutine builds linear spline interpolant INPUT PARAMETERS:
399 of 430
10/25/2011 03:12 PM
X Y N spline nodes, array[0..N-1] function values, array[0..N-1] points count (optional): * N>=2 * if given, only first N points are used to build spline * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y))
OUTPUT PARAMETERS: C spline interpolant ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. -- ALGLIB PROJECT -Copyright 24.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dbuildlinear( real_1d_array x, real_1d_array y, spline1dinterpolant& c); void alglib::spline1dbuildlinear( real_1d_array x, real_1d_array y, ae_int_t n, spline1dinterpolant& c); Examples: [1] [2]
spline1dcalc
function
/************************************************************************* This subroutine calculates the value of the spline at the given point X. INPUT PARAMETERS: C spline interpolant X point Result: S(x) -- ALGLIB PROJECT -Copyright 23.06.2007 by Bochkanov Sergey *************************************************************************/ double alglib::spline1dcalc(spline1dinterpolant c, double x); Examples: [1] [2]
spline1dconvcubic
function
/************************************************************************* This function solves following problem: given table y[] of function values at old nodes x[] and new nodes x2[], it calculates and returns table of function values y2[] (calculated at x2[]). This function yields same result as Spline1DBuildCubic() call followed by sequence of Spline1DDiff() calls, but it can be several times faster when called for ordered X[] and X2[].
400 of 430
10/25/2011 03:12 PM
INPUT PARAMETERS: X Y X2 -
old spline nodes function values new spline nodes
OPTIONAL PARAMETERS: N points count: * N>=2 * if given, only first N points from X/Y are used * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) BoundLType boundary condition type for the left boundary BoundL left boundary condition (first or second derivative, depending on the BoundLType) BoundRType boundary condition type for the right boundary BoundR right boundary condition (first or second derivative, depending on the BoundRType) N2 new points count: * N2>=2 * if given, only first N2 points from X2 are used * if not given, automatically detected from X2 size OUTPUT PARAMETERS: F2 ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. Function values are correctly reordered on return, so F2[I] is always equal to S(X2[I]) independently of points order. SETTING BOUNDARY VALUES: The BoundLType/BoundRType parameters can have the following values: * -1, which corresonds to the periodic (cyclic) boundary conditions. In this case: * both BoundLType and BoundRType must be equal to -1. * BoundL/BoundR are ignored * Y[last] is ignored (it is assumed to be equal to Y[first]). * 0, which corresponds to the parabolically terminated spline (BoundL and/or BoundR are ignored). * 1, which corresponds to the first derivative boundary condition * 2, which corresponds to the second derivative boundary condition * by default, BoundType=0 is used PROBLEMS WITH PERIODIC BOUNDARY CONDITIONS: Problems with periodic boundary conditions have Y[first_point]=Y[last_point]. However, this subroutine doesn't require you to specify equal values for the first and last points - it automatically forces them to be equal by copying Y[first_point] (corresponds to the leftmost, minimal X[]) to Y[last_point]. However it is recommended to pass consistent values of Y[], i.e. to make Y[first_point]=Y[last_point]. -- ALGLIB PROJECT -Copyright 03.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dconvcubic( real_1d_array x, real_1d_array y, real_1d_array x2, real_1d_array& y2); void alglib::spline1dconvcubic( real_1d_array x, function values at X2[]
401 of 430
10/25/2011 03:12 PM
real_1d_array y, ae_int_t n, ae_int_t boundltype, double boundl, ae_int_t boundrtype, double boundr, real_1d_array x2, ae_int_t n2, real_1d_array& y2); Examples: [1]
spline1dconvdiff2cubic
function
/************************************************************************* This function solves following problem: given table y[] of function values at old nodes x[] and new nodes x2[], it calculates and returns table of function values y2[], first and second derivatives d2[] and dd2[] (calculated at x2[]). This function yields same result as Spline1DBuildCubic() call followed by sequence of Spline1DDiff() calls, but it can be several times faster when called for ordered X[] and X2[]. INPUT PARAMETERS: X Y X2 old spline nodes function values new spline nodes
OPTIONAL PARAMETERS: N points count: * N>=2 * if given, only first N points from X/Y are used * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) BoundLType boundary condition type for the left boundary BoundL left boundary condition (first or second derivative, depending on the BoundLType) BoundRType boundary condition type for the right boundary BoundR right boundary condition (first or second derivative, depending on the BoundRType) N2 new points count: * N2>=2 * if given, only first N2 points from X2 are used * if not given, automatically detected from X2 size OUTPUT PARAMETERS: F2 D2 DD2 ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. Function values are correctly reordered on return, so F2[I] is always equal to S(X2[I]) independently of points order. SETTING BOUNDARY VALUES: The BoundLType/BoundRType parameters can have the following values: * -1, which corresonds to the periodic (cyclic) boundary conditions. In this case: function values at X2[] first derivatives at X2[] second derivatives at X2[]
402 of 430
10/25/2011 03:12 PM
* both BoundLType and BoundRType must be equal to -1. * BoundL/BoundR are ignored * Y[last] is ignored (it is assumed to be equal to Y[first]). which corresponds to the parabolically terminated spline (BoundL and/or BoundR are ignored). which corresponds to the first derivative boundary condition which corresponds to the second derivative boundary condition default, BoundType=0 is used
* * * *
0, 1, 2, by
PROBLEMS WITH PERIODIC BOUNDARY CONDITIONS: Problems with periodic boundary conditions have Y[first_point]=Y[last_point]. However, this subroutine doesn't require you to specify equal values for the first and last points - it automatically forces them to be equal by copying Y[first_point] (corresponds to the leftmost, minimal X[]) to Y[last_point]. However it is recommended to pass consistent values of Y[], i.e. to make Y[first_point]=Y[last_point]. -- ALGLIB PROJECT -Copyright 03.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dconvdiff2cubic( real_1d_array x, real_1d_array y, real_1d_array x2, real_1d_array& y2, real_1d_array& d2, real_1d_array& dd2); void alglib::spline1dconvdiff2cubic( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t boundltype, double boundl, ae_int_t boundrtype, double boundr, real_1d_array x2, ae_int_t n2, real_1d_array& y2, real_1d_array& d2, real_1d_array& dd2); Examples: [1]
spline1dconvdiffcubic
function
/************************************************************************* This function solves following problem: given table y[] of function values at old nodes x[] and new nodes x2[], it calculates and returns table of function values y2[] and derivatives d2[] (calculated at x2[]). This function yields same result as Spline1DBuildCubic() call followed by sequence of Spline1DDiff() calls, but it can be several times faster when called for ordered X[] and X2[]. INPUT PARAMETERS: X Y X2 old spline nodes function values new spline nodes
OPTIONAL PARAMETERS: N points count:
403 of 430
10/25/2011 03:12 PM
* N>=2 * if given, only first N points from X/Y are used * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) boundary condition type for the left boundary left boundary condition (first or second derivative, depending on the BoundLType) boundary condition type for the right boundary right boundary condition (first or second derivative, depending on the BoundRType) new points count: * N2>=2 * if given, only first N2 points from X2 are used * if not given, automatically detected from X2 size function values at X2[] first derivatives at X2[]
BoundLType BoundL BoundRType BoundR N2
OUTPUT PARAMETERS: F2 D2 ORDER OF POINTS
Subroutine automatically sorts points, so caller may pass unsorted array. Function values are correctly reordered on return, so F2[I] is always equal to S(X2[I]) independently of points order. SETTING BOUNDARY VALUES: The BoundLType/BoundRType parameters can have the following values: * -1, which corresonds to the periodic (cyclic) boundary conditions. In this case: * both BoundLType and BoundRType must be equal to -1. * BoundL/BoundR are ignored * Y[last] is ignored (it is assumed to be equal to Y[first]). * 0, which corresponds to the parabolically terminated spline (BoundL and/or BoundR are ignored). * 1, which corresponds to the first derivative boundary condition * 2, which corresponds to the second derivative boundary condition * by default, BoundType=0 is used PROBLEMS WITH PERIODIC BOUNDARY CONDITIONS: Problems with periodic boundary conditions have Y[first_point]=Y[last_point]. However, this subroutine doesn't require you to specify equal values for the first and last points - it automatically forces them to be equal by copying Y[first_point] (corresponds to the leftmost, minimal X[]) to Y[last_point]. However it is recommended to pass consistent values of Y[], i.e. to make Y[first_point]=Y[last_point]. -- ALGLIB PROJECT -Copyright 03.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dconvdiffcubic( real_1d_array x, real_1d_array y, real_1d_array x2, real_1d_array& y2, real_1d_array& d2); void alglib::spline1dconvdiffcubic( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t boundltype, double boundl, ae_int_t boundrtype, double boundr,
404 of 430
10/25/2011 03:12 PM
real_1d_array x2, ae_int_t n2, real_1d_array& y2, real_1d_array& d2); Examples: [1]
spline1ddiff
function
/************************************************************************* This subroutine differentiates the spline. INPUT PARAMETERS: C spline interpolant. X point Result: S DS D2S S(x) S'(x) S''(x)
-- ALGLIB PROJECT -Copyright 24.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1ddiff( spline1dinterpolant c, double x, double& s, double& ds, double& d2s);
spline1dgriddiff2cubic
function
/************************************************************************* This function solves following problem: given table y[] of function values at nodes x[], it calculates and returns tables of first and second function derivatives d1[] and d2[] (calculated at the same nodes x[]). This function yields same result as Spline1DBuildCubic() call followed by sequence of Spline1DDiff() calls, but it can be several times faster when called for ordered X[] and X2[]. INPUT PARAMETERS: X Y spline nodes function values
OPTIONAL PARAMETERS: N points count: * N>=2 * if given, only first N points are used * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) BoundLType boundary condition type for the left boundary BoundL left boundary condition (first or second derivative, depending on the BoundLType) BoundRType boundary condition type for the right boundary BoundR right boundary condition (first or second derivative, depending on the BoundRType) OUTPUT PARAMETERS:
405 of 430
10/25/2011 03:12 PM
D1 D2 ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. Derivative values are correctly reordered on return, so D[I] is always equal to S'(X[I]) independently of points order. SETTING BOUNDARY VALUES: The BoundLType/BoundRType parameters can have the following values: * -1, which corresonds to the periodic (cyclic) boundary conditions. In this case: * both BoundLType and BoundRType must be equal to -1. * BoundL/BoundR are ignored * Y[last] is ignored (it is assumed to be equal to Y[first]). * 0, which corresponds to the parabolically terminated spline (BoundL and/or BoundR are ignored). * 1, which corresponds to the first derivative boundary condition * 2, which corresponds to the second derivative boundary condition * by default, BoundType=0 is used PROBLEMS WITH PERIODIC BOUNDARY CONDITIONS: Problems with periodic boundary conditions have Y[first_point]=Y[last_point]. However, this subroutine doesn't require you to specify equal values for the first and last points - it automatically forces them to be equal by copying Y[first_point] (corresponds to the leftmost, minimal X[]) to Y[last_point]. However it is recommended to pass consistent values of Y[], i.e. to make Y[first_point]=Y[last_point]. -- ALGLIB PROJECT -Copyright 03.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dgriddiff2cubic( real_1d_array x, real_1d_array y, real_1d_array& d1, real_1d_array& d2); void alglib::spline1dgriddiff2cubic( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t boundltype, double boundl, ae_int_t boundrtype, double boundr, real_1d_array& d1, real_1d_array& d2); Examples: [1] S' values at X[] S'' values at X[]
spline1dgriddiffcubic
function
/************************************************************************* This function solves following problem: given table y[] of function values at nodes x[], it calculates and returns table of function derivatives d[] (calculated at the same nodes x[]). This function yields same result as Spline1DBuildCubic() call followed by sequence of Spline1DDiff() calls, but it can be several times faster when
406 of 430
10/25/2011 03:12 PM
called for ordered X[] and X2[]. INPUT PARAMETERS: X Y spline nodes function values
OPTIONAL PARAMETERS: N points count: * N>=2 * if given, only first N points are used * if not given, automatically detected from X/Y sizes (len(X) must be equal to len(Y)) BoundLType boundary condition type for the left boundary BoundL left boundary condition (first or second derivative, depending on the BoundLType) BoundRType boundary condition type for the right boundary BoundR right boundary condition (first or second derivative, depending on the BoundRType) OUTPUT PARAMETERS: D ORDER OF POINTS Subroutine automatically sorts points, so caller may pass unsorted array. Derivative values are correctly reordered on return, so D[I] is always equal to S'(X[I]) independently of points order. SETTING BOUNDARY VALUES: The BoundLType/BoundRType parameters can have the following values: * -1, which corresonds to the periodic (cyclic) boundary conditions. In this case: * both BoundLType and BoundRType must be equal to -1. * BoundL/BoundR are ignored * Y[last] is ignored (it is assumed to be equal to Y[first]). * 0, which corresponds to the parabolically terminated spline (BoundL and/or BoundR are ignored). * 1, which corresponds to the first derivative boundary condition * 2, which corresponds to the second derivative boundary condition * by default, BoundType=0 is used PROBLEMS WITH PERIODIC BOUNDARY CONDITIONS: Problems with periodic boundary conditions have Y[first_point]=Y[last_point]. However, this subroutine doesn't require you to specify equal values for the first and last points - it automatically forces them to be equal by copying Y[first_point] (corresponds to the leftmost, minimal X[]) to Y[last_point]. However it is recommended to pass consistent values of Y[], i.e. to make Y[first_point]=Y[last_point]. -- ALGLIB PROJECT -Copyright 03.09.2010 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dgriddiffcubic( real_1d_array x, real_1d_array y, real_1d_array& d); void alglib::spline1dgriddiffcubic( real_1d_array x, real_1d_array y, ae_int_t n, ae_int_t boundltype, double boundl, ae_int_t boundrtype, derivative values at X[]
407 of 430
10/25/2011 03:12 PM
double boundr, real_1d_array& d); Examples: [1]
spline1dintegrate
function
/************************************************************************* This subroutine integrates the spline. INPUT PARAMETERS: C spline interpolant. X right bound of the integration interval [a, x], here 'a' denotes min(x[]) Result: integral(S(t)dt,a,x) -- ALGLIB PROJECT -Copyright 23.06.2007 by Bochkanov Sergey *************************************************************************/ double alglib::spline1dintegrate(spline1dinterpolant c, double x);
spline1dlintransx
function
/************************************************************************* This subroutine performs linear transformation of the spline argument. INPUT PARAMETERS: C spline interpolant. A, Btransformation coefficients: x = A*t + B Result: C transformed spline -- ALGLIB PROJECT -Copyright 30.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dlintransx(spline1dinterpolant c, double a, double b);
spline1dlintransy
function
/************************************************************************* This subroutine performs linear transformation of the spline. INPUT PARAMETERS: C spline interpolant. A, Btransformation coefficients: S2(x) = A*S(x) + B Result: C transformed spline -- ALGLIB PROJECT -Copyright 30.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dlintransy(spline1dinterpolant c, double a, double b);
spline1dunpack
function
408 of 430
10/25/2011 03:12 PM
/************************************************************************* This subroutine unpacks the spline into the coefficients table. INPUT PARAMETERS: C spline interpolant. X point Result: Tbl coefficients table, unpacked format, array[0..N-2, 0..5]. For I = 0...N-2: Tbl[I,0] = X[i] Tbl[I,1] = X[i+1] Tbl[I,2] = C0 Tbl[I,3] = C1 Tbl[I,4] = C2 Tbl[I,5] = C3 On [x[i], x[i+1]] spline is equals to: S(x) = C0 + C1*t + C2*t^2 + C3*t^3 t = x-x[i]
-- ALGLIB PROJECT -Copyright 29.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline1dunpack( spline1dinterpolant c, ae_int_t& n, real_2d_array& tbl);
spline1d_d_convdiff example
using namespace alglib; int main(int argc, char **argv) { // // We use cubic spline to do resampling, i.e. having // values of f(x)=x^2 sampled at 5 equidistant nodes on [-1,+1] // we calculate values/derivatives of cubic spline on // another grid (equidistant with 9 nodes on [-1,+1]) // WITHOUT CONSTRUCTION OF SPLINE OBJECT. // // There are efficient functions spline1dconvcubic(), // spline1dconvdiffcubic() and spline1dconvdiff2cubic() // for such calculations. // // We use default boundary conditions ("parabolically terminated // spline") because cubic spline built with such boundary conditions // will exactly reproduce any quadratic f(x). // // Actually, we could use natural conditions, but we feel that // spline which exactly reproduces f() will show us more // understandable results. // real_1d_array x_old = "[-1.0,-0.5,0.0,+0.5,+1.0]"; real_1d_array y_old = "[+1.0,0.25,0.0,0.25,+1.0]";
409 of 430
10/25/2011 03:12 PM
real_1d_array real_1d_array real_1d_array real_1d_array x_new = "[-1.00,-0.75,-0.50,-0.25,0.00,+0.25,+0.50,+0.75,+1.00]"; y_new; d1_new; d2_new;
// // First, conversion without differentiation. // // spline1dconvcubic(x_old, y_old, x_new, y_new); printf("%s\n", y_new.tostring(3).c_str()); // EXPECTED: [1.0000, 0.5625, 0.2500, 0.0625, 0.0000, 0.0625,
// // Then, conversion with differentiation (first derivatives only) // // spline1dconvdiffcubic(x_old, y_old, x_new, y_new, d1_new); printf("%s\n", y_new.tostring(3).c_str()); // EXPECTED: [1.0000, 0.5625, 0.2500, 0.0625, 0.0000, 0.0625, printf("%s\n", d1_new.tostring(3).c_str()); // EXPECTED: [-2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0
// // Finally, conversion with first and second derivatives // // spline1dconvdiff2cubic(x_old, y_old, x_new, y_new, d1_new, d2_new); printf("%s\n", y_new.tostring(3).c_str()); // EXPECTED: [1.0000, 0.5625, 0.2500, 0.0625, 0.0000, 0.0625, printf("%s\n", d1_new.tostring(3).c_str()); // EXPECTED: [-2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0 printf("%s\n", d2_new.tostring(3).c_str()); // EXPECTED: [2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0, 2.0] return 0; }
spline1d_d_cubic example
using namespace alglib; int main(int argc, char **argv) { // // We use cubic spline to interpolate f(x)=x^2 sampled // at 5 equidistant nodes on [-1,+1]. // // First, we use default boundary conditions ("parabolically terminated // spline") because cubic spline built with such boundary conditions // will exactly reproduce any quadratic f(x). // // Then we try to use natural boundary conditions // d2S(-1)/dx^2 = 0.0 // d2S(+1)/dx^2 = 0.0 // and see that such spline interpolated f(x) with small error. // real_1d_array x = "[-1.0,-0.5,0.0,+0.5,+1.0]"; real_1d_array y = "[+1.0,0.25,0.0,0.25,+1.0]"; double t = 0.25; double v;
410 of 430
10/25/2011 03:12 PM
spline1dinterpolant s; ae_int_t natural_bound_type = 2; // // Test exact boundary conditions: build S(x), calculare S(0.25) // (almost same as original function) // spline1dbuildcubic(x, y, s); v = spline1dcalc(s, t); printf("%.4f\n", double(v)); // EXPECTED: 0.0625 // // Test natural boundary conditions: build S(x), calculare S(0.25) // (small interpolation error) // spline1dbuildcubic(x, y, 5, natural_bound_type, 0.0, natural_bound_type, 0.0, s); v = spline1dcalc(s, t); printf("%.3f\n", double(v)); // EXPECTED: 0.0580 return 0; }
spline1d_d_griddiff example
using namespace alglib; int main(int argc, char **argv) { // // We use cubic spline to do grid differentiation, i.e. having // values of f(x)=x^2 sampled at 5 equidistant nodes on [-1,+1] // we calculate derivatives of cubic spline at nodes WITHOUT // CONSTRUCTION OF SPLINE OBJECT. // // There are efficient functions spline1dgriddiffcubic() and // spline1dgriddiff2cubic() for such calculations. // // We use default boundary conditions ("parabolically terminated // spline") because cubic spline built with such boundary conditions // will exactly reproduce any quadratic f(x). // // Actually, we could use natural conditions, but we feel that // spline which exactly reproduces f() will show us more // understandable results. // real_1d_array x = "[-1.0,-0.5,0.0,+0.5,+1.0]"; real_1d_array y = "[+1.0,0.25,0.0,0.25,+1.0]"; real_1d_array d1; real_1d_array d2; // // We calculate first derivatives: they must be equal to 2*x // spline1dgriddiffcubic(x, y, d1); printf("%s\n", d1.tostring(3).c_str()); // EXPECTED: [-2.0, -1.0, 0.0, +1.0, +2.0]
411 of 430
10/25/2011 03:12 PM
// // Now test griddiff2, which returns first AND second derivatives. // First derivative is 2*x, second is equal to 2.0 // spline1dgriddiff2cubic(x, y, d1, d2); printf("%s\n", d1.tostring(3).c_str()); // EXPECTED: [-2.0, -1.0, 0.0, +1.0, +2.0] printf("%s\n", d2.tostring(3).c_str()); // EXPECTED: [ 2.0, 2.0, 2.0, 2.0, 2.0] return 0; }
spline1d_d_linear example
using namespace alglib; int main(int argc, char **argv) { // // We use piecewise linear spline to interpolate f(x)=x^2 sampled // at 5 equidistant nodes on [-1,+1]. // real_1d_array x = "[-1.0,-0.5,0.0,+0.5,+1.0]"; real_1d_array y = "[+1.0,0.25,0.0,0.25,+1.0]"; double t = 0.25; double v; spline1dinterpolant s; // build spline spline1dbuildlinear(x, y, s); // calculate S(0.25) - it is quite different from 0.25^2=0.0625 v = spline1dcalc(s, t); printf("%.4f\n", double(v)); // EXPECTED: 0.125 return 0; }
spline2d
Classes
subpackage
spline2dinterpolant
Functions
spline2dbuildbicubic spline2dbuildbilinear spline2dcalc spline2ddiff spline2dlintransf spline2dlintransxy
412 of 430
10/25/2011 03:12 PM
spline2dresamplebic ubic spline2dresamplebilinear spline2dunpack
Examples
spline2dinterpolant
class
/************************************************************************* 2-dimensional spline inteprolant *************************************************************************/ class spline2dinterpolant { };
spline2dbuildbicubic
function
/************************************************************************* This subroutine builds bicubic spline coefficients table. Input parameters: X spline abscissas, array[0..N-1] Y spline ordinates, array[0..M-1] F function values, array[0..M-1,0..N-1] M,N grid size, M>=2, N>=2 Output parameters: C spline interpolant -- ALGLIB PROJECT -Copyright 05.07.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline2dbuildbicubic( real_1d_array x, real_1d_array y, real_2d_array f, ae_int_t m, ae_int_t n, spline2dinterpolant& c);
spline2dbuildbilinear
function
/************************************************************************* This subroutine builds bilinear spline coefficients table. Input parameters: X spline abscissas, array[0..N-1] Y spline ordinates, array[0..M-1] F function values, array[0..M-1,0..N-1] M,N grid size, M>=2, N>=2 Output parameters: C spline interpolant -- ALGLIB PROJECT -Copyright 05.07.2007 by Bochkanov Sergey *************************************************************************/
413 of 430
10/25/2011 03:12 PM
void alglib::spline2dbuildbilinear( real_1d_array x, real_1d_array y, real_2d_array f, ae_int_t m, ae_int_t n, spline2dinterpolant& c);
spline2dcalc
function
/************************************************************************* This subroutine calculates the value of the bilinear or bicubic spline at the given point X. Input parameters: C coefficients table. Built by BuildBilinearSpline or BuildBicubicSpline. X, Ypoint Result: S(x,y) -- ALGLIB PROJECT -Copyright 05.07.2007 by Bochkanov Sergey *************************************************************************/ double alglib::spline2dcalc(spline2dinterpolant c, double x, double y);
spline2ddiff
function
/************************************************************************* This subroutine calculates the value of the bilinear or bicubic spline at the given point X and its derivatives. Input parameters: C spline interpolant. X, Ypoint Output parameters: F S(x,y) FX dS(x,y)/dX FY dS(x,y)/dY FXY d2S(x,y)/dXdY -- ALGLIB PROJECT -Copyright 05.07.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline2ddiff( spline2dinterpolant c, double x, double y, double& f, double& fx, double& fy, double& fxy);
spline2dlintransf
function
/*************************************************************************
414 of 430
10/25/2011 03:12 PM
This subroutine performs linear transformation of the spline. Input parameters: C spline interpolant. A, Btransformation coefficients: S2(x,y) = A*S(x,y) + B Output parameters: C transformed spline -- ALGLIB PROJECT -Copyright 30.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline2dlintransf(spline2dinterpolant c, double a, double b);
spline2dlintransxy
function
/************************************************************************* This subroutine performs linear transformation of the spline argument. Input parameters: C spline interpolant AX, BX transformation coefficients: x = A*t + B AY, BY transformation coefficients: y = A*u + B Result: C transformed spline -- ALGLIB PROJECT -Copyright 30.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline2dlintransxy( spline2dinterpolant c, double ax, double bx, double ay, double by);
spline2dresamplebicubic
function
/************************************************************************* Bicubic spline resampling Input parameters: A OldHeight OldWidth NewHeight NewWidth function values at the old grid, array[0..OldHeight-1, 0..OldWidth-1] old grid height, OldHeight>1 old grid width, OldWidth>1 new grid height, NewHeight>1 new grid width, NewWidth>1 function values at the new grid, array[0..NewHeight-1, 0..NewWidth-1]
Output parameters: B -
-- ALGLIB routine -15 May, 2007 Copyright by Bochkanov Sergey *************************************************************************/ void alglib::spline2dresamplebicubic( real_2d_array a, ae_int_t oldheight,
415 of 430
10/25/2011 03:12 PM
ae_int_t oldwidth, real_2d_array& b, ae_int_t newheight, ae_int_t newwidth);
spline2dresamplebilinear
function
/************************************************************************* Bilinear spline resampling Input parameters: A OldHeight OldWidth NewHeight NewWidth function values at the old grid, array[0..OldHeight-1, 0..OldWidth-1] old grid height, OldHeight>1 old grid width, OldWidth>1 new grid height, NewHeight>1 new grid width, NewWidth>1 function values at the new grid, array[0..NewHeight-1, 0..NewWidth-1]
Output parameters: B -
-- ALGLIB routine -09.07.2007 Copyright by Bochkanov Sergey *************************************************************************/ void alglib::spline2dresamplebilinear( real_2d_array a, ae_int_t oldheight, ae_int_t oldwidth, real_2d_array& b, ae_int_t newheight, ae_int_t newwidth);
spline2dunpack
function
/************************************************************************* This subroutine unpacks two-dimensional spline into the coefficients table Input parameters: C spline interpolant. Result: M, NTbl grid size (x-axis and y-axis) coefficients table, unpacked format, [0..(N-1)*(M-1)-1, 0..19]. For I = 0...M-2, J=0..N-2: K = I*(N-1)+J Tbl[K,0] = X[j] Tbl[K,1] = X[j+1] Tbl[K,2] = Y[i] Tbl[K,3] = Y[i+1] Tbl[K,4] = C00 Tbl[K,5] = C01 Tbl[K,6] = C02 Tbl[K,7] = C03 Tbl[K,8] = C10 Tbl[K,9] = C11 ... Tbl[K,19] = C33
416 of 430
10/25/2011 03:12 PM
On each grid square spline is equals to: S(x) = SUM(c[i,j]*(xî)*(y^j), i=0..3, j=0..3) t = x-x[j] u = y-y[i] -- ALGLIB PROJECT -Copyright 29.06.2007 by Bochkanov Sergey *************************************************************************/ void alglib::spline2dunpack( spline2dinterpolant c, ae_int_t& m, ae_int_t& n, real_2d_array& tbl);
stest
subpackage
Functions
onesamplesigntest
Examples
onesamplesigntest
function
/************************************************************************* Sign test This test checks three hypotheses about the median of the given sample. The following tests are performed: * two-tailed test (null hypothesis - the median is equal to the given value) * left-tailed test (null hypothesis - the median is greater than or equal to the given value) * right-tailed test (null hypothesis - the median is less than or equal to the given value) Requirements: * the scale of measurement should be ordinal, interval or ratio the test could not be applied to nominal variables). (i.e.
The test is non-parametric and doesn't require distribution X to be normal Input parameters: X sample. Array whose index goes from 0 to N-1. N size of the sample. Median assumed median value. Output parameters: BothTails LeftTail RightTail p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected.
417 of 430
10/25/2011 03:12 PM
While calculating p-values high-precision binomial distribution approximation is used, so significance levels have about 15 exact digits. -- ALGLIB -Copyright 08.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::onesamplesigntest( real_1d_array x, ae_int_t n, double median, double& bothtails, double& lefttail, double& righttail);
studenttdistr
Functions
invstudenttdistribution studenttdistribution
subpackage
Examples
invstudenttdistribution
function
/************************************************************************* Functional inverse of Student's t distribution Given probability p, finds the argument t such that stdtr(k,t) is equal to p. ACCURACY: Tested at random 1 <= k <= 100. The "domain" refers to p: Relative error: arithmetic domain # trials peak rms IEEE .001,.999 25000 5.7e-15 8.0e-16 IEEE 10^-6,.001 25000 2.0e-12 2.9e-14 Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::invstudenttdistribution(ae_int_t k, double p);
studenttdistribution
function
/************************************************************************* Student's t distribution Computes the integral from minus infinity to t of the Student t distribution with integer k > 0 degrees of freedom: t | | | 2 -(k+1)/2
418 of 430
10/25/2011 03:12 PM
| ( (k+1)/2 ) ---------------------sqrt( k pi ) | ( k/2 ) | ( x ) | ( 1 + --- ) | ( k ) | | | -inf.
dx
Relation to incomplete beta integral: 1 - stdtr(k,t) = 0.5 * incbet( k/2, 1/2, z ) where z = k/(k + t**2). For t < -2, this is the method of computation. For higher t, a direct method is derived from integration by parts. Since the function is symmetric about t=0, the area under the right tail of the density is found by calling the function with -t instead of t. ACCURACY: Tested at random 1 <= k <= 25. The "domain" refers to t. Relative error: arithmetic domain # trials peak rms IEEE -100,-2 50000 5.9e-15 1.4e-15 IEEE -2,100 500000 2.7e-15 4.9e-17 Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 1995, 2000 by Stephen L. Moshier *************************************************************************/ double alglib::studenttdistribution(ae_int_t k, double t);
studentttests
Functions
studentttest1 studentttest2 unequalvariancettest
subpackage
Examples
studentttest1
function
/************************************************************************* One-sample t-test This test checks three hypotheses about the mean of the given sample. The following tests are performed: * two-tailed test (null hypothesis - the mean is equal to the given value) * left-tailed test (null hypothesis - the mean is greater than or equal to the given value) * right-tailed test (null hypothesis - the mean is less than or equal to the given value). The test is based on the assumption that a given sample has a normal
419 of 430
10/25/2011 03:12 PM
distribution and an unknown dispersion. If the distribution differs from normal, the test will work incorrectly. Input parameters: X sample. Array whose index goes from 0 to N-1. N size of sample. Mean assumed value of the mean. Output parameters: BothTails LeftTail RightTail p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected. sharply
-- ALGLIB -Copyright 08.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::studentttest1( real_1d_array x, ae_int_t n, double mean, double& bothtails, double& lefttail, double& righttail);
studentttest2
function
/************************************************************************* Two-sample pooled test This test checks three hypotheses about the mean of the given samples. The following tests are performed: * two-tailed test (null hypothesis - the means are equal) * left-tailed test (null hypothesis - the mean of the first sample is greater than or equal to the mean of the second sample) * right-tailed test (null hypothesis - the mean of the first sample is less than or equal to the mean of the second sample). Test is based on the following assumptions: * given samples have normal distributions * dispersions are equal * samples are independent. Input parameters: X sample 1. Array whose index goes from 0 to N-1. N size of sample. Y sample 2. Array whose index goes from 0 to M-1. M size of sample. Output parameters: BothTails LeftTail RightTail p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test.
420 of 430
10/25/2011 03:12 PM
If RightTail is less than the given significance level the null hypothesis is rejected. -- ALGLIB -Copyright 18.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::studentttest2( real_1d_array x, ae_int_t n, real_1d_array y, ae_int_t m, double& bothtails, double& lefttail, double& righttail);
unequalvariancettest
function
/************************************************************************* Two-sample unpooled test This test checks three hypotheses about the mean of the given samples. The following tests are performed: * two-tailed test (null hypothesis - the means are equal) * left-tailed test (null hypothesis - the mean of the first sample is greater than or equal to the mean of the second sample) * right-tailed test (null hypothesis - the mean of the first sample is less than or equal to the mean of the second sample). Test is based on the following assumptions: * given samples have normal distributions * samples are independent. Dispersion equality is not required Input X N Y M parameters: - sample 1. Array whose index goes from 0 to N-1. - size of the sample. - sample 2. Array whose index goes from 0 to M-1. - size of the sample. p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected.
Output parameters: BothTails LeftTail RightTail -
-- ALGLIB -Copyright 18.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::unequalvariancettest( real_1d_array x, ae_int_t n, real_1d_array y, ae_int_t m, double& bothtails, double& lefttail, double& righttail);
421 of 430
10/25/2011 03:12 PM
svd
subpackage
Functions
rmatrixsvd
Examples
rmatrixsvd
function
/************************************************************************* Singular value decomposition of a rectangular matrix. The algorithm calculates the singular value decomposition of a matrix of size MxN: A = U * S * V^T The algorithm finds the singular values and, optionally, matrices U and V^T. The algorithm can find both first min(M,N) columns of matrix U and rows of matrix V^T (singular vectors), and matrices U and V^T wholly (of sizes MxM and NxN respectively). Take into account that the subroutine does not return matrix V but V^T. Input parameters: A matrix to be decomposed. Array whose indexes range within [0..M-1, 0..N-1]. M number of rows in matrix A. N number of columns in matrix A. UNeeded 0, 1 or 2. See the description of the parameter U. VTNeeded 0, 1 or 2. See the description of the parameter VT. AdditionalMemory If the parameter: * equals 0, the algorithm doesnt use additional memory (lower requirements, lower performance). * equals 1, the algorithm uses additional memory of size min(M,N)*min(M,N) of real numbers. It often speeds up the algorithm. * equals 2, the algorithm uses additional memory of size M*min(M,N) of real numbers. It allows to get a maximum performance. The recommended value of the parameter is 2. contains singular values in descending order. if UNeeded=0, U isn't changed, the left singular vectors are not calculated. if Uneeded=1, U contains left singular vectors (first min(M,N) columns of matrix U). Array whose indexes range within [0..M-1, 0..Min(M,N)-1]. if UNeeded=2, U contains matrix U wholly. Array whose indexes range within [0..M-1, 0..M-1]. if VTNeeded=0, VT isnt changed, the right singular vectors are not calculated. if VTNeeded=1, VT contains right singular vectors (first min(M,N) rows of matrix V^T). Array whose indexes range within [0..min(M,N)-1, 0..N-1]. if VTNeeded=2, VT contains matrix V^T wholly. Array whose indexes range within [0..N-1, 0..N-1].
Output parameters: W U -
VT
-- ALGLIB --
422 of 430
10/25/2011 03:12 PM
Copyright 2005 by Bochkanov Sergey *************************************************************************/ bool alglib::rmatrixsvd( real_2d_array a, ae_int_t m, ae_int_t n, ae_int_t uneeded, ae_int_t vtneeded, ae_int_t additionalmemory, real_1d_array& w, real_2d_array& u, real_2d_array& vt);
trfac
subpackage
Functions
cmatrixlu hpdmatrixcholesky rmatrixlu spdmatrixcholesky
Examples
cmatrixlu
function
/************************************************************************* LU decomposition of a general complex matrix with row pivoting A * * * is represented as A = P*L*U, where: L is lower unitriangular matrix U is upper triangular matrix P = P0*P1*...*PK, K=min(M,N)-1, Pi - permutation matrix for I and Pivots[I]
This is cache-oblivous implementation of LU decomposition. It is optimized for square matrices. As for rectangular matrices: * best case - M>>N * worst case - N>>M, small M, large N, matrix does not fit in CPU cache INPUT PARAMETERS: A array[0..M-1, 0..N-1]. M number of rows in matrix A. N number of columns in matrix A. OUTPUT PARAMETERS: A matrices L and U in compact form: * L is stored under main diagonal * U is stored on and above main diagonal Pivots permutation matrix in compact form. array[0..Min(M-1,N-1)]. -- ALGLIB routine -10.01.2010 Bochkanov Sergey *************************************************************************/ void alglib::cmatrixlu(
423 of 430
10/25/2011 03:12 PM
complex_2d_array& a, ae_int_t m, ae_int_t n, integer_1d_array& pivots);
hpdmatrixcholesky
function
/************************************************************************* Cache-oblivious Cholesky decomposition The algorithm computes Cholesky decomposition of a Hermitian definite matrix. The result of an algorithm is a representation A=U'*U or A=L*L' (here X' detones conj(X^T)). positiveof A as
INPUT PARAMETERS: A upper or lower triangle of a factorized matrix. array with elements [0..N-1, 0..N-1]. N size of matrix A. IsUpper if IsUpper=True, then A contains an upper triangle of a symmetric matrix, otherwise A contains a lower one. OUTPUT PARAMETERS: A the result of factorization. If IsUpper=True, then the upper triangle contains matrix U, so that A = U'*U, and the elements below the main diagonal are not modified. Similarly, if IsUpper = False. RESULT: If the matrix is positive-definite, the function returns True. Otherwise, the function returns False. Contents of A is not determined in such case. -- ALGLIB routine -15.12.2009 Bochkanov Sergey *************************************************************************/ bool alglib::hpdmatrixcholesky( complex_2d_array& a, ae_int_t n, bool isupper);
rmatrixlu
function
/************************************************************************* LU decomposition of a general real matrix with row pivoting A * * * is represented as A = P*L*U, where: L is lower unitriangular matrix U is upper triangular matrix P = P0*P1*...*PK, K=min(M,N)-1, Pi - permutation matrix for I and Pivots[I]
This is cache-oblivous implementation of LU decomposition. It is optimized for square matrices. As for rectangular matrices: * best case - M>>N * worst case - N>>M, small M, large N, matrix does not fit in CPU cache INPUT PARAMETERS: A array[0..M-1, 0..N-1]. M number of rows in matrix A.
424 of 430
10/25/2011 03:12 PM
N number of columns in matrix A.
OUTPUT PARAMETERS: A matrices L and U in compact form: * L is stored under main diagonal * U is stored on and above main diagonal Pivots permutation matrix in compact form. array[0..Min(M-1,N-1)]. -- ALGLIB routine -10.01.2010 Bochkanov Sergey *************************************************************************/ void alglib::rmatrixlu( real_2d_array& a, ae_int_t m, ae_int_t n, integer_1d_array& pivots);
spdmatrixcholesky
function
/************************************************************************* Cache-oblivious Cholesky decomposition The algorithm computes Cholesky decomposition of a symmetric definite matrix. The result of an algorithm is a representation A=U^T*U or A=L*L^T positiveof A as
INPUT PARAMETERS: A upper or lower triangle of a factorized matrix. array with elements [0..N-1, 0..N-1]. N size of matrix A. IsUpper if IsUpper=True, then A contains an upper triangle of a symmetric matrix, otherwise A contains a lower one. OUTPUT PARAMETERS: A the result of factorization. If IsUpper=True, then the upper triangle contains matrix U, so that A = U^T*U, and the elements below the main diagonal are not modified. Similarly, if IsUpper = False. RESULT: If the matrix is positive-definite, the function returns True. Otherwise, the function returns False. Contents of A is not determined in such case. -- ALGLIB routine -15.12.2009 Bochkanov Sergey *************************************************************************/ bool alglib::spdmatrixcholesky( real_2d_array& a, ae_int_t n, bool isupper);
trigintegrals
subpackage
425 of 430
10/25/2011 03:12 PM
Functions
hyperbolicsinecosineintegrals sinecosineintegrals
Examples
hyperbolicsinecosineintegrals
function
/************************************************************************* Hyperbolic sine and cosine integrals Approximates the integrals x | | Chi(x) = eul + ln x + | | | 0 x Shi(x) = | | | | | 0 sinh t -----t dt
cosh t - 1 ----------t
dt,
where eul = 0.57721566490153286061 is Euler's constant. The integrals are evaluated by power series for x < 8 and by Chebyshev expansions for x between 8 and 88. For large x, both functions approach exp(x)/2x. Arguments greater than 88 in magnitude return MAXNUM. ACCURACY: Test interval 0 to 88. Relative error: arithmetic function # trials peak rms IEEE Shi 30000 6.9e-16 1.6e-16 Absolute error, except relative when |Chi| > 1: IEEE Chi 30000 8.4e-16 1.4e-16 Cephes Math Library Release 2.8: June, 2000 Copyright 1984, 1987, 2000 by Stephen L. Moshier *************************************************************************/ void alglib::hyperbolicsinecosineintegrals( double x, double& shi, double& chi);
sinecosineintegrals
function
/************************************************************************* Sine and cosine integrals
426 of 430
10/25/2011 03:12 PM
Evaluates the integrals x Ci(x) = eul + ln x + | | | 0 cos t - 1 --------- dt, t
x Si(x) = | | | 0 sin t ----- dt t
where eul = 0.57721566490153286061 is Euler's constant. The integrals are approximated by rational functions. For x > 8 auxiliary functions f(x) and g(x) are employed such that Ci(x) = f(x) sin(x) - g(x) cos(x) Si(x) = pi/2 - f(x) cos(x) - g(x) sin(x) ACCURACY: Test interval = [0,50]. Absolute error, except relative when > 1: arithmetic function # trials peak IEEE Si 30000 4.4e-16 IEEE Ci 30000 6.9e-16
rms 7.3e-17 5.1e-17
Cephes Math Library Release 2.1: January, 1989 Copyright 1984, 1987, 1989 by Stephen L. Moshier *************************************************************************/ void alglib::sinecosineintegrals(double x, double& si, double& ci);
variancetests
Functions
ftest onesamplevarianc etest
subpackage
Examples
ftest
function
/************************************************************************* Two-sample F-test This test checks three hypotheses about dispersions of the given samples. The following tests are performed: * two-tailed test (null hypothesis - the dispersions are equal) * left-tailed test (null hypothesis - the dispersion of the first sample is greater than or equal to the dispersion of the second sample).
427 of 430
10/25/2011 03:12 PM
* right-tailed test (null hypothesis - the dispersion of the first sample is less than or equal to the dispersion of the second sample) The test is based on the following assumptions: * the given samples have normal distributions * the samples are independent. Input parameters: X sample N sample Y sample M sample Output parameters: BothTails LeftTail RightTail 1. Array whose index goes from 0 to N-1. size. 2. Array whose index goes from 0 to M-1. size. p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected. p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected.
-- ALGLIB -Copyright 19.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::ftest( real_1d_array x, ae_int_t n, real_1d_array y, ae_int_t m, double& bothtails, double& lefttail, double& righttail);
onesamplevariancetest
function
/************************************************************************* One-sample chi-square test This test checks three hypotheses about the dispersion of the given sample The following tests are performed: * two-tailed test (null hypothesis - the dispersion equals the given number) * left-tailed test (null hypothesis - the dispersion is greater than or equal to the given number) * right-tailed test (null hypothesis - dispersion is less than or equal to the given number). Test is based on the following assumptions: * the given sample has a normal distribution. Input parameters: X N Variance Output parameters: BothTails sample 1. Array whose index goes from 0 to N-1. size of the sample. dispersion value to compare with. p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected.
428 of 430
10/25/2011 03:12 PM
LeftTail RightTail p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected.
-- ALGLIB -Copyright 19.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::onesamplevariancetest( real_1d_array x, ae_int_t n, double variance, double& bothtails, double& lefttail, double& righttail);
wsr
subpackage
Functions
wilcoxonsignedranktest
Examples
wilcoxonsignedranktest
function
/************************************************************************* Wilcoxon signed-rank test This test checks three hypotheses about the median of the given sample. The following tests are performed: * two-tailed test (null hypothesis - the median is equal to the given value) * left-tailed test (null hypothesis - the median is greater than or equal to the given value) * right-tailed test (null hypothesis - the median is less than or equal to the given value) Requirements: * the scale of measurement should be ordinal, interval or ratio (i.e. the test could not be applied to nominal variables). * the distribution should be continuous and symmetric relative to its median. * number of distinct values in the X array should be greater than 4 The test is non-parametric and doesn't require distribution X to be normal Input parameters: X sample. Array whose index goes from 0 to N-1. N size of the sample. Median assumed median value. Output parameters: BothTails p-value for two-tailed test. If BothTails is less than the given significance level the null hypothesis is rejected.
429 of 430
10/25/2011 03:12 PM
LeftTail RightTail p-value for left-tailed test. If LeftTail is less than the given significance level, the null hypothesis is rejected. p-value for right-tailed test. If RightTail is less than the given significance level the null hypothesis is rejected. us the if
To calculate p-values, special approximation is used. This method lets calculate p-values with two decimal places in interval [0.0001, 1]. "Two decimal places" does not sound very impressive, but in practice relative error of less than 1% is enough to make a decision. There is no approximation outside the [0.0001, 1] interval. Therefore, the significance level outlies this interval, the test returns 0.0001.
-- ALGLIB -Copyright 08.09.2006 by Bochkanov Sergey *************************************************************************/ void alglib::wilcoxonsignedranktest( real_1d_array x, ae_int_t n, double e, double& bothtails, double& lefttail, double& righttail);
430 of 430
10/25/2011 03:12 PM

Alglib Man

Загружено:

Сведения о документе

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Alglib Man

Загружено:

Авторское право:

Доступные форматы

http://www.alglib.net/translator/man/manual.cpp.

1.2 Documentation license

1.3 Reference Manual and User Guide

2 Getting started with ALGLIB

2.2.3 Optimization settings

2.3 Compiling ALGLIB

2.3.2 Configuring for your compiler

2.3.3 Improving performance (CPU-specific and OS-specific optimizations)

2.4 Using ALGLIB

2.4.5 Working with vectors and matrices

// all double double double

2.4.6 Using functions: 'expert' and 'friendly' interfaces

// 'expert' interface is used // 'friendly' interface - input size is // automatically determined

// it won't work because sizes of x and y2 // are inconsistent

2.4.7 Handling errors

2.4.8 Working with Level 1 BLAS functions

2.5 Advanced topics

3 ALGLIB reference manual

conv corr fft fht

idwint lsfit polint pspline

Rational interpolation/fitting 1D spline interpolation/fitting 2D spline interpolation

minbleic mincg mincomp minlbfgs minlm minqp

package densesolver nleq

normaldistr poissondistr psif studenttdistr trigintegrals

/************************************************************************* Matrix-vector product: y := op(A)*x

/************************************************************************* Airy function

/************************************************************************* Adaptive integration results Called after AutoGKIteration returned False.

/************************************************************************* Median calculation. Input parameters:

/************************************************************************* Percentile calculation. Input parameters: X sample (array indexes: [0..N-1])

/************************************************************************* Modified Bessel function of order one

/************************************************************************* Bessel function of order one

/************************************************************************* Beta function | (a) | (b) -----------. | (a+b)

/************************************************************************* Binomial distribution

chebyshevcalculate chebyshevcoeffic ients chebyshevsum fromchebyshev

/************************************************************************* Inverse of complemented Chi-square distribution

pearsoncorrelationsignific anc e spearmanrankcorrelationsignific anc e

/************************************************************************* *************************************************************************/ class densesolverreport { double r1; double rinf; };

/************************************************************************* *************************************************************************/ class decisionforest { };

OUTPUT PARAMETERS: Info -

/************************************************************************* This function serializes data structure to string.

ellipticintegrale ellipticintegralk ellipticintegralkhighprec ision incompleteelliptic integrale incompleteelliptic integralk

using the approximation P(x) x log x Q(x).

pi/2 | | | dt | -----------------| 2 | | sqrt( 1 - m sin t ) 0

where m = 1 - m1, using the approximation P(x) log x Q(x).

Cephes *************************************************************************/ double alglib::ellipticintegralkhighprecision(double m1);

dt -----------------2 sqrt( 1 - m sin t )

/************************************************************************* Finding the eigenvalues and eigenvectors of a Hermitian matrix

/************************************************************************* Exponential integral Ei(x) x Ei(x) = | | -|| | -inf t e --t dt .

Not defined for x <= 0. See also expn.c.

/************************************************************************* Exponential integral En(x) Evaluates the exponential integral inf. | | |

fcdistribution fdistribution invfdistribution

/************************************************************************* Natural logarithm of gamma function Input parameters:

-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey *************************************************************************/

OUTPUT PARAMETERS: Info -

-- ALGLIB -Copyright 12.05.2009 by Bochkanov Sergey

hermitecalculate hermitecoefficients hermitesum

/************************************************************************* This function generates random integer number in [0, N)

/************************************************************************* IDW interpolant. *************************************************************************/ class idwinterpolant { };

incompletegamma incompletegammac invincompletegammac

# trials 200000 200000

Output parameters: InvA -

laguerrecalculate laguerrecoefficients laguerresum

OUTPUT PARAMETERS: Info -

NPoints NVars NClasses

/* */ class densesolverreport { double r1; double rinf; };

/* */ class decisionforest { };

/* IDW interpolant. */ class idwinterpolant { };

/* */ class linearmodel { };

/* */ class logitmodel

void ptr), real_1d_array &grad, void ptr

void ptr), real_1d_array &grad, void ptr

/* */ class minasastate { };

/* */ class minlbfgsstate { };

/* */ class multilayerperceptron { };

/* Neural networks ensemble */ class mlpensemble { };

/* */ class kdtree { };

/* */ class nleqstate { };

/* */ class odesolverreport { ae_int_t nfev; ae_int_t terminationtype; };

/* */ class odesolverstate { };

/* Barycentric interpolant. */ class barycentricinterpolant {

/* 1-dimensional spline inteprolant */ class spline1dinterpolant { };