Mercurial > hg > segmenter-vamp-plugin

annotate armadillo-2.4.4/README.txt @ 29:0b1494e959d2 slimline

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Build fixes
author Chris Cannam
date Thu, 10 May 2012 17:21:26 +0100
parents 8b6102e2a9b0
children
rev   line source
max@0 1 === Contents ===
max@0 2
max@0 3 1: Introduction
max@0 4 1.1: Citation Details
max@0 5
max@0 6 2: Installation
max@0 7 2.0: Preliminaries
max@0 8 2.1: Manual Installation
max@0 9 2.2: Installation on Linux / Mac OS X
max@0 10 2.3: Installation on MS Windows
max@0 11
max@0 12 3: Compiling Programs and Linking
max@0 13 3.0: Examples
max@0 14 3.1: Compiling & Linking on Linux / Mac OS X
max@0 15 3.2: Compiling & Linking on MS Windows
max@0 16
max@0 17 4: Caveats
max@0 18 4.0: Support for ATLAS
max@0 19 4.1: Support for ACML and Intel MKL
max@0 20
max@0 21 5: Documentation / Reference Manual
max@0 22
max@0 23 6: FAQs and Bug Reports
max@0 24
max@0 25 7: Credits
max@0 26
max@0 27 8: License
max@0 28
max@0 29
max@0 30
max@0 31
max@0 32 === 1.0: Introduction ===
max@0 33
max@0 34 Armadillo is a C++ linear algebra library (matrix maths)
max@0 35 aiming towards a good balance between speed and ease of use.
max@0 36 Integer, floating point and complex numbers are supported,
max@0 37 as well as a subset of trigonometric and statistics functions.
max@0 38 Various matrix decompositions are provided through optional
max@0 39 integration with LAPACK or high-performance LAPACK-compatible
max@0 40 libraries.
max@0 41
max@0 42 A delayed evaluation approach is employed (during compile time)
max@0 43 to combine several operations into one and reduce (or eliminate)
max@0 44 the need for temporaries. This is accomplished through recursive
max@0 45 templates and template meta-programming.
max@0 46
max@0 47 This library is useful if C++ has been decided as the language
max@0 48 of choice (due to speed and/or integration capabilities),
max@0 49 rather than another language like Matlab or Octave.
max@0 50 It is distributed under a license that is useful in both
max@0 51 open-source and proprietary contexts.
max@0 52
max@0 53 Armadillo is primarily developed at NICTA (Australia),
max@0 54 with contributions from around the world.
max@0 55 More information about NICTA can be obtained from:
max@0 56 http://nicta.com.au
max@0 57
max@0 58
max@0 59
max@0 60 === 1.1: Citation Details ===
max@0 61
max@0 62 If you use Armadillo in your research and/or software,
max@0 63 we would appreciate a citation to the following tech report:
max@0 64
max@0 65 Conrad Sanderson.
max@0 66 Armadillo: An Open Source C++ Linear Algebra Library for
max@0 67 Fast Prototyping and Computationally Intensive Experiments.
max@0 68 Technical Report, NICTA, 2010.
max@0 69
max@0 70
max@0 71
max@0 72 === 2.0: Installation: Preliminaries ===
max@0 73
max@0 74 Armadillo makes extensive use of template meta-programming,
max@0 75 recursive templates and template based function overloading.
max@0 76 As such, C++ compilers which do not fully implement the C++
max@0 77 standard may not work correctly.
max@0 78
max@0 79 The functionality of Armadillo is partly dependent on other
max@0 80 libraries -- mainly LAPACK and BLAS. Armadillo can work without
max@0 81 LAPACK or BLAS, but its functionality will be reduced.
max@0 82 In particular, basic functionality will be available
max@0 83 (eg. matrix addition and multiplication), but things like
max@0 84 eigen decomposition or will not be. Matrix multiplication
max@0 85 (mainly for big matrices) may not be as fast.
max@0 86
max@0 87 For manual installation on all systems, see section 2.1.
max@0 88
max@0 89 For installation on Linux / Mac OS X systems, see section 2.2.
max@0 90 The Linux installation is also likely to work on other Unix-like
max@0 91 systems, such as FreeBSD, NetBSD, OpenBSD, Solaris, CygWin, etc.
max@0 92
max@0 93 For installation on MS Windows, see section 2.3.
max@0 94
max@0 95
max@0 96
max@0 97 === 2.1: Manual Installation ===
max@0 98
max@0 99 The manual installation is comprised of 3 steps:
max@0 100
max@0 101 * Step 1:
max@0 102 Copy the entire "include" folder to a convenient location
max@0 103 and tell your compiler to use that location for header files
max@0 104 (in addition to the locations it uses already).
max@0 105 Alternatively, you can use the "include" folder directly.
max@0 106
max@0 107 * Step 2:
max@0 108 Modify "include/armadillo_bits/config.hpp" to indicate
max@0 109 which libraries are currently available on your system.
max@0 110 For example, if you have LAPACK and BLAS present,
max@0 111 uncomment the following lines:
max@0 112
max@0 113 #define ARMA_USE_LAPACK
max@0 114 #define ARMA_USE_BLAS
max@0 115
max@0 116 * Step 3:
max@0 117 If you have LAPACK and/or BLAS present, configure your
max@0 118 compiler to link with these libraries.
max@0 119
max@0 120 You can also link with the the equivalent of LAPACK and BLAS,
max@0 121 eg. Intel's MKL or AMD's ACML. Under Mac OS X, link using
max@0 122 -framework Accelerate
max@0 123
max@0 124
max@0 125
max@0 126 === 2.2: Installation on Linux / Mac OS X ===
max@0 127
max@0 128 If you have installed Armadillo using an RPM or DEB package,
max@0 129 you don't need to do anything else. Otherwise read on.
max@0 130
max@0 131 You can use the manual installation process as described in
max@0 132 section 2.1, or the following CMake based automatic installation.
max@0 133
max@0 134 * Step 1:
max@0 135 If CMake is not already be present on your system, download
max@0 136 it from http://www.cmake.org
max@0 137
max@0 138 On major Linux systems (such as Fedora, Ubuntu, Debian, etc),
max@0 139 cmake is available as a pre-built package, though it may need
max@0 140 to be explicitly installed (using a tool such as PackageKit,
max@0 141 yum, rpm, apt, aptitude, etc).
max@0 142
max@0 143 * Step 2:
max@0 144 If you have BLAS and/or LAPACK, install them before installing
max@0 145 Armadillo. Under Mac OS X this is not necessary.
max@0 146
max@0 147 On Linux systems it is recommended that the following libraries
max@0 148 are present: LAPACK, BLAS, ATLAS and Boost. LAPACK and BLAS are
max@0 149 the most important. If you have ATLAS and Boost, it's also necessary
max@0 150 to have the corresponding header files installed.
max@0 151
max@0 152 * Step 3:
max@0 153 Open a shell (command line), change into the directory that was
max@0 154 created by unpacking the armadillo archive, and type the following
max@0 155 commands:
max@0 156
max@0 157 cmake .
max@0 158 make
max@0 159
max@0 160 The full stop separated from "cmake" by a space is important.
max@0 161 CMake will figure out what other libraries are currently installed
max@0 162 and will modify Armadillo's configuration correspondingly.
max@0 163 CMake will also generate a run-time armadillo library, which is a
max@0 164 combined alias for all the relevant libraries present on your system
max@0 165 (eg. BLAS, LAPACK and ATLAS).
max@0 166
max@0 167 If you need to re-run cmake, it's a good idea to first delete the
max@0 168 "CMakeCache.txt" file (not "CMakeLists.txt").
max@0 169
max@0 170 * Step 4:
max@0 171 If you have access to root/administrator/superuser privileges,
max@0 172 first enable the privileges (eg. through "su" or "sudo")
max@0 173 and then type the following command:
max@0 174
max@0 175 make install
max@0 176
max@0 177 If you don't have root/administrator/superuser privileges,
max@0 178 type the following command:
max@0 179
max@0 180 make install DESTDIR=my_usr_dir
max@0 181
max@0 182 where "my_usr_dir" is for storing C++ headers and library files.
max@0 183 Make sure your C++ compiler is configured to use the sub-directories
max@0 184 present within this directory.
max@0 185
max@0 186
max@0 187
max@0 188 === 2.3: Installation on MS Windows ===
max@0 189
max@0 190 There is currently no automatic installation for Windows.
max@0 191 Please use the manual installation process described in section 2.1.
max@0 192
max@0 193 Pre-compiled 32 bit versions of BLAS and LAPACK libraries
max@0 194 for Windows are provided in the "examples/libs_win32" folder.
max@0 195 If the provided libraries don't work for you, see section 3.2.
max@0 196
max@0 197
max@0 198
max@0 199 === 3.0: Compiling Programs and Linking: Examples ===
max@0 200
max@0 201 The "examples" directory contains several quick example programs
max@0 202 that use the Armadillo library. If Armadillo was installed manually
max@0 203 (ie. according to section 2.1), you will also need to explicitly
max@0 204 link your programs with the libraries that were specified in
max@0 205 "include/armadillo_bits/config.hpp".
max@0 206
max@0 207 "example1.cpp" may require the BLAS library or its equivalent.
max@0 208 "example2.cpp" requires the LAPACK library or its equivalent
max@0 209 (eg. the Accelerate framework on Mac OS X).
max@0 210
max@0 211 You may get errors at compile or run time if BLAS and/or LAPACK
max@0 212 functions are not available.
max@0 213
max@0 214 NOTE: As Armadillo is a template library, we recommended that
max@0 215 optimisation is enabled during compilation. For example,
max@0 216 for the GCC compiler use -O1 or -O2
max@0 217
max@0 218
max@0 219
max@0 220 === 3.1: Compiling & Linking on Linux / Mac OS X ===
max@0 221
max@0 222 Please see "examples/Makefile", which may may need to be configured
max@0 223 for your system. If Armadillo header files were installed in a
max@0 224 non-standard location, you will need to modify "examples/Makefile"
max@0 225 to tell the compiler where they are.
max@0 226
max@0 227 In general, programs which use Armadillo are compiled along these lines:
max@0 228 g++ example1.cpp -o example1 -O1 -larmadillo
max@0 229
max@0 230 (you may also need to specify the include directory via the -I switch)
max@0 231
max@0 232 If you get linking errors, or if Armadillo was installed manually
max@0 233 and you specified that LAPACK and BLAS are available, you will
max@0 234 need to explicitly link with LAPACK and BLAS (or their equivalents),
max@0 235 for example:
max@0 236 g++ example1.cpp -o example1 -O1 -llapack -lblas
max@0 237
max@0 238 (you may also need to specify the library directory via the -L switch)
max@0 239
max@0 240 Notes:
max@0 241
max@0 242 * under most Linux systems, using "-llapack -lblas" should be enough;
max@0 243 however, on Ubuntu and Debian you may need to add "-lgfortran"
max@0 244
max@0 245 * under Mac OS X, try "-framework Accelerate" or "-llapack -lblas"
max@0 246 (the Accelerate option is usually the fastest)
max@0 247
max@0 248 * under the Sun Studio compiler, try "-library=sunperf"
max@0 249
max@0 250
max@0 251
max@0 252 === 3.2: Compiling & Linking on MS Windows ===
max@0 253
max@0 254 As a courtesy, we've provided pre-compiled 32 bit versions of
max@0 255 LAPACK and BLAS for Windows, as well as MSVC project files to
max@0 256 compile example1.cpp and example2.cpp.
max@0 257 The project files are stored in the following folders:
max@0 258 examples/example1_win32
max@0 259 examples/example2_win32
max@0 260
max@0 261 The LAPACK and BLAS libraries are stored in:
max@0 262 examples/lib_win32
max@0 263
max@0 264 Note that on 64 bit systems (such as Windows 7), dedicated
max@0 265 64 bit versions of BLAS and LAPACK are considerably faster.
max@0 266
max@0 267 If you're not using MSVC, or you're getting "use of LAPACK needs
max@0 268 to be enabled" messages, you will need to manually modify
max@0 269 "include/armadillo_bits/config.hpp" to enable the use of
max@0 270 LAPACK and BLAS. Please see section 2.1 for more information.
max@0 271
max@0 272 The MSCV project files were tested on 32 bit Windows XP with
max@0 273 Visual C++ 2008 (Express Edition). You may need to make adaptations
max@0 274 for 64 bit systems, later versions of Windows and/or the compiler.
max@0 275 For example, you may have to enable or disable the ARMA_BLAS_LONG
max@0 276 and ARMA_BLAS_UNDERSCORE macros in "armadillo_bits/config.hpp".
max@0 277
max@0 278 To preserve our sanity, we (Armadillo developers) don't use Windows
max@0 279 on a regular basis, and as such can't help you with the adaptations.
max@0 280 For best results we recommend using an operating system that's
max@0 281 more reliable and more suitable for heavy duty work,
max@0 282 such as Linux or Mac OS X.
max@0 283
max@0 284 The pre-compiled versions of LAPACK and BLAS were downloaded from:
max@0 285 http://www.fi.muni.cz/~xsvobod2/misc/lapack/
max@0 286
max@0 287 If the provided libraries don't work for you, try these versions:
max@0 288 http://www.stanford.edu/~vkl/code/libs.html
max@0 289 http://icl.cs.utk.edu/lapack-for-windows/lapack/
max@0 290 http://software.intel.com/en-us/intel-mkl/
max@0 291 http://www.amd.com/acml
max@0 292
max@0 293 (the MKL and ACML libraries are generally the fastest)
max@0 294
max@0 295
max@0 296 If you want to compile BLAS and LAPACK yourself, you can find
max@0 297 the original sources at:
max@0 298 http://www.netlib.org/blas/
max@0 299 http://www.netlib.org/lapack/
max@0 300
max@0 301 If you encounter issues with the MS Visual C++ compiler,
max@0 302 the following high-quality compilers are useful alternatives:
max@0 303
max@0 304 * GCC (part MinGW)
max@0 305 http://www.mingw.org/
max@0 306
max@0 307 * GCC (part of CygWin)
max@0 308 http://www.cygwin.com/
max@0 309
max@0 310 * Intel's C++ compiler
max@0 311 http://software.intel.com/en-us/intel-compilers/
max@0 312
max@0 313 If using GCC, you'll need version 4.0 or better.
max@0 314 If using Intel's C++ compiler, you'll need version 10.0 or better.
max@0 315
max@0 316
max@0 317
max@0 318 === 4.0: Caveats: Support for ATLAS ===
max@0 319
max@0 320 Armadillo can use the ATLAS library for faster versions of
max@0 321 certain LAPACK and BLAS functions. Not all ATLAS functions are
max@0 322 currently used, and as such LAPACK should still be installed.
max@0 323
max@0 324 The minimum recommended version of ATLAS is 3.8.
max@0 325 Old versions (eg. 3.6) can produce incorrect results
max@0 326 as well as corrupting memory, leading to random crashes.
max@0 327
max@0 328 Users of Ubuntu and Debian based systems should explicitly
max@0 329 check that version 3.6 is not installed. It's better to
max@0 330 remove the old version and use the standard LAPACK library.
max@0 331
max@0 332
max@0 333
max@0 334 === 4.1: Caveats: Support for ACML and Intel MKL ===
max@0 335
max@0 336 Armadillo can work with AMD Core Math Library and Intel's
max@0 337 Math Kernel Library (MKL), however there are several caveats.
max@0 338
max@0 339 On Linux systems, ACML and MKL are typically installed in a
max@0 340 non-standard location, which can cause problems during linking.
max@0 341
max@0 342 Before installing Armadillo, the system should know where the ACML or MKL
max@0 343 libraries are located (eg., "/opt/intel/mkl/10.2.2.025/lib/em64t/").
max@0 344 This can be achieved by setting the LD_LIBRARY_PATH environment variable,
max@0 345 or, for a more permanent solution, adding the location of the libraries
max@0 346 to "/etc/ld.so.conf". It may also be possible to store a text file
max@0 347 with the location in the "/etc/ld.so.conf.d" directory.
max@0 348 In the latter two cases you will need to run "ldconfig" afterwards.
max@0 349
max@0 350 The default installations of ACML 4.4.0 and MKL 10.2.2.025 are known
max@0 351 to have issues with SELinux, which is turned on by default in Fedora
max@0 352 (and possibly RHEL). The problem may manifest itself during run-time,
max@0 353 where the run-time linker reports permission problems.
max@0 354 It is possible to work around the problem by applying an appropriate
max@0 355 SELinux type to all ACML and MKL libraries.
max@0 356
max@0 357 If you have ACML or MKL installed and they are persistently giving
max@0 358 you problems during linking, you can disable the support for them
max@0 359 by editing the "CMakeLists.txt" file, deleting "CMakeCache.txt" and
max@0 360 re-running the CMake based installation. Specifically, comment out
max@0 361 the lines containing:
max@0 362 INCLUDE(ARMA_FindMKL)
max@0 363 INCLUDE(ARMA_FindACMLMP)
max@0 364 INCLUDE(ARMA_FindACML)
max@0 365
max@0 366
max@0 367
max@0 368 === 5: Documentation / Reference Manual ===
max@0 369
max@0 370 A reference manual (user documentation) is available at
max@0 371 http://arma.sourceforge.net or in the "docs" directory.
max@0 372 Use a web browser to open the "docs/index.html" file.
max@0 373
max@0 374 The user documentation explains how to use Armadillo's
max@0 375 classes and functions, with snippets of example code.
max@0 376
max@0 377
max@0 378
max@0 379 === 6: FAQs and Bug Reports ===
max@0 380
max@0 381 Answers to Frequently Asked Questions (FAQs) can be found at:
max@0 382 http://arma.sourceforge.net/faq.html
max@0 383
max@0 384 This library has gone through extensive testing and
max@0 385 has been successfully used in production environments.
max@0 386 However, as with almost all software, it's impossible
max@0 387 to guarantee 100% correct functionality.
max@0 388
max@0 389 If you find a bug in the library (or the documentation),
max@0 390 we are interested in hearing about it. Please make a small
max@0 391 self-contained program which exposes the bug and send the
max@0 392 program source (as well as the bug description) to the
max@0 393 developers. The developers' contact details are available at:
max@0 394 http://arma.sourceforge.net/contact.html
max@0 395
max@0 396
max@0 397
max@0 398 === 7: Credits ===
max@0 399
max@0 400 Main sponsoring organisation:
max@0 401 - NICTA
max@0 402 http://nicta.com.au
max@0 403
max@0 404 Main developers:
max@0 405 - Conrad Sanderson - http://itee.uq.edu.au/~conrad/
max@0 406 - Ian Cullinan
max@0 407 - Dimitrios Bouzas
max@0 408 - Stanislav Funiak
max@0 409
max@0 410 Contributors:
max@0 411 - Eric R. Anderson
max@0 412 - Benoît Bayol
max@0 413 - Salim Bcoin
max@0 414 - Justin Bedo
max@0 415 - Darius Braziunas
max@0 416 - Ted Campbell
max@0 417 - Clement Creusot
max@0 418 - Ryan Curtin
max@0 419 - Chris Davey
max@0 420 - Dirk Eddelbuettel
max@0 421 - Romain Francois
max@0 422 - Piotr Gawron
max@0 423 - Charles Gretton
max@0 424 - Benjamin Herzog
max@0 425 - Edmund Highcock
max@0 426 - Kshitij Kulshreshtha
max@0 427 - Oka Kurniawan
max@0 428 - Simen Kvaal
max@0 429 - David Lawrence
max@0 430 - Carlos Mendes
max@0 431 - Artem Novikov
max@0 432 - Martin Orlob
max@0 433 - Ken Panici
max@0 434 - Adam Piątyszek
max@0 435 - Jayden Platell
max@0 436 - Vikas Reddy
max@0 437 - Ola Rinta-Koski
max@0 438 - James Sanders
max@0 439 - Alexander Scherbatey
max@0 440 - Gerhard Schreiber
max@0 441 - Shane Stainsby
max@0 442 - Petter Strandmark
max@0 443 - Paul Torfs
max@0 444 - Simon Urbanek
max@0 445 - Arnold Wiliem
max@0 446 - Yong Kang Wong
max@0 447
max@0 448
max@0 449
max@0 450 === 8: License ===
max@0 451
max@0 452 Please see the "LICENSE.txt" file.
max@0 453
max@0 454
max@0 455