LAPACKE/README

   1 -------------------------------------------------------------------------------
   2                              C Interface to LAPACK
   3                                    README
   4 -------------------------------------------------------------------------------
   5 Introduction
   6 -------------------------------------------------------------------------------
   7
   8 This library is a part of reference implementation for the C interface to
   9 LAPACK project according to the specifications described at the forum for
  10 the Intel(R) Math Kernel Library (Intel(R) MKL):
  11 http://software.intel.com/en-us/forums/showthread.php?t=61234
  12
  13 This implementation provides a native C interface to LAPACK routines available
  14 at www.netlib.org/lapack to facilitate usage of LAPACK functionality
  15 for C programmers.
  16 This implementation introduces:
  17 - row-major and column-major matrix layout controlled by the first function
  18   parameter;
  19 - an implementation with working arrays (middle-level interface) as well as
  20   without working arrays (high-level interface);
  21 - input scalars passed by value;
  22 - error code as a return value instead of the INFO parameter.
  23
  24 This implementation supports both the ILP64 and LP64 programming models,
  25 and different complex type styles: structure, C99.
  26
  27 This implementation includes interfaces for the LAPACK-3.2.1 Driver and
  28 Computational routines only.
  29
  30 -------------------------------------------------------------------------------
  31 Product Directories
  32 -------------------------------------------------------------------------------
  33
  34 The installation directory of this package has the following structure:
  35
  36 src                - C interface source files
  37 utils              - C interface auxiliary files
  38 include            - header files for C interface
  39
  40 -------------------------------------------------------------------------------
  41 Installation
  42 -------------------------------------------------------------------------------
  43
  44 The reference code for the C interface to LAPACK is built similarly to the
  45 Basic Linear Algebra Subprograms (BLAS) and LAPACK. The build system produces
  46 a static binary lapacke.a.
  47
  48 You need to provide a make.inc file in the top directory that defines the
  49 compiler, compiler flags, names for binaries to be created/linked to. You may
  50 choose the appropriate LP64/ILP64 model, convenient complex type style,
  51 LAPACKE name pattern, and/or redefine system malloc/free in make.inc. Several
  52 examples of make.inc are provided.
  53
  54 After setting up the make.inc, you can build C interface to LAPACK by typing
  55
  56 make lapacke
  57
  58 -------------------------------------------------------------------------------
  59 Handling Complex Types
  60 -------------------------------------------------------------------------------
  61
  62 The interface uses complex types lapack_complex_float/lapack_complex_double.
  63 You have several options to define them:
  64
  65 1) C99 complex types (default):
  66
  67 #define lapack_complex_float    float _Complex
  68 #define lapack_complex_double   double _Complex
  69
  70 2) C structure option (set by enabling in the configuration file):
  71 -DHAVE_LAPACK_CONFIG_H  -DLAPACK_COMPLEX_STRUCTURE
  72
  73 typedef struct { float real, imag; } _lapack_complex_float;
  74 typedef struct { double real, imag; } _lapack_complex_double;
  75 #define lapack_complex_float  _lapack_complex_float
  76 #define lapack_complex_double _lapack_complex_double
  77
  78 3) C++ complex types (set by enabling in the configuration file):
  79 -DHAVE_LAPACK_CONFIG_H -DLAPACK_COMPLEX_CPP
  80
  81 #define lapack_complex_float std::complex<float>
  82 #define lapack_complex_double std::complex<double>
  83
  84 You have to compile the interface with C++ compiler with C++ types.
  85
  86 4) Custom complex types:
  87 -DLAPACK_COMPLEX_CUSTOM
  88
  89 To use custom complex types, you need to:
  90 - Define lapack_complex_float/lapack_complex_double types on your own.
  91 - Optionally define lapack_make_complex_float/lapack_make_complex_double_real
  92   functions if you want to build the testing suite supplied. Use these
  93   functions for the testing system. Their purpose is to make a complex value of
  94   a real part re, imaginary part im. The prototypes are as follows:
  95
  96    lapack_complex_float lapack_make_complex_float( float re, float im );
  97    lapack_complex_double lapack_make_complex_double( double re, double im );
  98
  99 -------------------------------------------------------------------------------
 100 Choosing ILP64 Data Model
 101 -------------------------------------------------------------------------------
 102 To choose ILP64 data model (set by enabling in the configuration file), use the
 103 following options:
 104
 105 -DHAVE_LAPACK_CONFIG_H  -DLAPACK_ILP64
 106
 107 -------------------------------------------------------------------------------
 108 Using Predicate Functions
 109 -------------------------------------------------------------------------------
 110
 111 The functions
 112
 113 lapacke_?gees/lapacke_?gees_work
 114 lapacke_?geesx/lapacke_?geesx_work
 115 lapacke_?geev/lapacke_?geev_work
 116 lapacke_?geevx/lapacke_?geevx_work
 117
 118 require the pointer to a predicate function as an argument of a predefined type
 119 such as:
 120
 121 typedef lapack_logical (*LAPACK_S_SELECT2) ( const float*, const float* );
 122
 123 The purpose and format of these predicate functions are described in the LAPACK
 124 documentation. This interface passes the pointer to the corresponding LAPACK
 125 routine as it is.
 126
 127 Be cautious with return values of the logical type if you link against LAPACK
 128 compiled with Fortran compiler. Whereas all non-zero values are treated as TRUE
 129 generally, some Fortran compilers may rely on a certain TRUE value, so you will
 130 have to use the same TRUE value in the predicate function to be consistent with
 131 LAPACK implementation.
 132
 133 -------------------------------------------------------------------------------
 134 Implementation Details
 135 -------------------------------------------------------------------------------
 136
 137 The current C interface implementation consists of wrappers to LAPACK routines.
 138 The row-major matrices are transposed on entry to and on exit from the LAPACK
 139 routine, if needed. Top-level interfaces additionally allocate/deallocate
 140 working space on entry to and on exit from the LAPACK routine.
 141
 142 Because of possible additional transpositions, a routine called with
 143 this interface may require more memory space and run slower than the
 144 corresponding LAPACK routine.
 145
 146 -------------------------------------------------------------------------------
 147 Disclaimer and Legal Information
 148 -------------------------------------------------------------------------------
 149
 150 INFORMATION IN THIS DOCUMENT IS PROVIDED IN CONNECTION WITH INTEL(R)
 151 PRODUCTS. NO LICENSE, EXPRESS OR IMPLIED, BY ESTOPPEL OR OTHERWISE, TO
 152 ANY INTELLECTUAL PROPERTY RIGHTS IS GRANTED BY THIS DOCUMENT.  EXCEPT
 153 AS PROVIDED IN INTEL'S TERMS AND CONDITIONS OF SALE FOR SUCH PRODUCTS,
 154 INTEL ASSUMES NO LIABILITY WHATSOEVER, AND INTEL DISCLAIMS ANY EXPRESS
 155 OR IMPLIED WARRANTY, RELATING TO SALE AND/OR USE OF INTEL PRODUCTS
 156 INCLUDING LIABILITY OR WARRANTIES RELATING TO FITNESS FOR A PARTICULAR
 157 PURPOSE, MERCHANTABILITY, OR INFRINGEMENT OF ANY PATENT, COPYRIGHT OR
 158 OTHER INTELLECTUAL PROPERTY RIGHT.  UNLESS OTHERWISE AGREED IN WRITING
 159 BY INTEL, THE INTEL PRODUCTS ARE NOT DESIGNED NOR INTENDED FOR ANY
 160 APPLICATION IN WHICH THE FAILURE OF THE INTEL PRODUCT COULD CREATE A
 161 SITUATION WHERE PERSONAL INJURY OR DEATH MAY OCCUR.
 162
 163 Intel may make changes to specifications and product descriptions at
 164 any time, without notice. Designers must not rely on the absence or
 165 characteristics of any features or instructions marked "reserved" or
 166 "undefined." Intel reserves these for future definition and shall have
 167 no responsibility whatsoever for conflicts or incompatibilities
 168 arising from future changes to them. The information here is subject
 169 to change without notice. Do not finalize a design with this
 170 information.
 171
 172 The products described in this document may contain design defects or
 173 errors known as errata which may cause the product to deviate from
 174 published specifications. Current characterized errata are available
 175 on request.
 176
 177 Contact your local Intel sales office or your distributor to obtain
 178 the latest specifications and before placing your product order.
 179 Copies of documents which have an order number and are referenced in
 180 this document, or other Intel literature, may be obtained by calling
 181 1-800-548-4725, or go to http://www.intel.com/design/literature.htm
 182
 183 Intel processor numbers are not a measure of performance. Processor
 184 numbers differentiate features within each processor family, not
 185 across different processor families. See
 186 http://www.intel.com/products/processor_number for details.
 187
 188 This document contains information on products in the design phase of
 189 development.
 190
 191 BunnyPeople, Celeron, Celeron Inside, Centrino, Centrino Atom,
 192 Centrino Atom Inside, Centrino Inside, Centrino logo, Core Inside,
 193 FlashFile, i960, InstantIP, Intel, Intel logo, Intel386, Intel486,
 194 IntelDX2, IntelDX4, IntelSX2, Intel Atom, Intel Atom Inside, Intel
 195 Core, Intel Inside, Intel Inside logo, Intel. Leap ahead., Intel. Leap
 196 ahead.  logo, Intel NetBurst, Intel NetMerge, Intel NetStructure,
 197 Intel SingleDriver, Intel SpeedStep, Intel StrataFlash, Intel Viiv,
 198 Intel vPro, XScale, IPLink, Itanium, Itanium Inside, MCS, MMX, Oplus,
 199 OverDrive, Intel PDCharm, Pentium, Pentium Inside, skoool, Sound Mark,
 200 The Journey Inside, VTune, Xeon, and Xeon Inside are trademarks of
 201 Intel Corporation in the U.S. and other countries.
 202
 203
 204 * Other names and brands may be claimed as the property of others.
 205
 206 Copyright (C) 2011, Intel Corporation. All rights reserved.
 207
 208