include/gmx_arpack.h

   1 /*
   2  * This file is part of the GROMACS molecular simulation package.
   3  *
   4  * This file is part of Gromacs        Copyright (c) 1991-2004
   5  * David van der Spoel, Erik Lindahl, University of Groningen.
   6  * Copyright (c) 2012, by the GROMACS development team, led by
   7  * David van der Spoel, Berk Hess, Erik Lindahl, and including many
   8  * others, as listed in the AUTHORS file in the top-level source
   9  * directory and at http://www.gromacs.org.
  10  *
  11  * GROMACS is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Lesser General Public License
  13  * as published by the Free Software Foundation; either version 2.1
  14  * of the License, or (at your option) any later version.
  15  *
  16  * GROMACS is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Lesser General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Lesser General Public
  22  * License along with GROMACS; if not, see
  23  * http://www.gnu.org/licenses, or write to the Free Software Foundation,
  24  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA.
  25  *
  26  * If you want to redistribute modifications to GROMACS, please
  27  * consider that scientific software is very special. Version
  28  * control is crucial - bugs must be traceable. We will be happy to
  29  * consider code for inclusion in the official distribution, but
  30  * derived work must not be called official GROMACS. Details are found
  31  * in the README & COPYING files - if they are missing, get the
  32  * official version at http://www.gromacs.org.
  33  *
  34  * To help us fund GROMACS development, we humbly ask that you cite
  35  * the research papers on the package. Check out http://www.gromacs.org.
  36  */
  37
  38 #ifndef _GMX_ARPACK_H
  39 #define _GMX_ARPACK_H
  40
  41 #include "visibility.h"
  42 #ifdef __cplusplus
  43 extern "C" {
  44 #endif
  45
  46 /*! \file
  47  * \brief Selected routines from ARPACK
  48  *
  49  * This file contains a subset of ARPACK functions to perform
  50  * diagonalization and SVD for sparse matrices in Gromacs.
  51  *
  52  * Consult the main ARPACK site for detailed documentation:
  53  * http://www.caam.rice.edu/software/ARPACK/
  54  *
  55  * Below, we just list the options and any specific differences
  56  * from ARPACK. The code is essentially the same, but the routines
  57  * have been made thread-safe by using extra workspace arrays.
  58  */
  59
  60 #ifndef F77_FUNC
  61 #define F77_FUNC(name,NAME) name ## _
  62 #endif
  63
  64
  65 /*! \brief Implicitly Restarted Arnoldi Iteration, double precision.
  66  *
  67  *  Reverse communication interface for the Implicitly Restarted Arnoldi
  68  *  Iteration.  For symmetric problems this reduces to a variant of the
  69  *  Lanczos method. See the ARPACK site for details.
  70  *
  71  *  \param ido     Reverse communication flag. Set to 0 first time.
  72  *                 Upon return with ido=-1 or ido=1 you should calculate
  73  *                 Y=A*X and recall the routine. Return with ido=2 means
  74  *                 Y=B*X should be calculated. ipntr[0] is the pointer in
  75  *                 workd for X, ipntr[1] is the index for Y.
  76  *                 Return with ido=99 means it finished.
  77  *  \param bmat    'I' for standard eigenproblem, 'G' for generalized.
  78  *  \param n       Order of eigenproblem.
  79  *  \param which   Which eigenvalues to calculate. 'LA' for largest
  80  *                 algebraic, 'SA' for smallest algebraic, 'LM' for largest
  81  *                 magnitude, 'SM' for smallest magnitude, and finally
  82  *                 'BE' (both ends) to calculate half from each end of
  83  *                 the spectrum.
  84  *  \param nev     Number of eigenvalues to calculate. 0<nev<n.
  85  *  \param tol     Tolerance. Machine precision of it is 0.
  86  *  \param resid   Optional starting residual vector at input if info=1,
  87  *                 otherwise a random one is used. Final residual vector on
  88  *                 return.
  89  *  \param ncv     Number of columns in matrix v.
  90  *  \param v       N*NCV matrix. V contain the Lanczos basis vectors.
  91  *  \param ldv     Leading dimension of v.
  92  *  \param iparam  Integer array, size 11. Same contents as arpack.
  93  *  \param ipntr   Integer array, size 11. Points to starting locations
  94  *                 in the workd/workl arrays. Same contents as arpack.
  95  *  \param workd   Double precision work array, length 3*n+4.
  96  *                 Provide the same array for all calls, and don't touch it.
  97  *                 IMPORTANT: This is 4 units larger than standard ARPACK!
  98  *  \param iwork   Integer work array, size 80.
  99  *                 Provide the same array for all calls, and don't touch it.
 100  *                 IMPORTANT: New argument compared to standard ARPACK!
 101  *  \param workl   Double precision work array, length lwork.
 102  *  \param lworkl  Length of the work array workl. Must be at least ncv*(ncv+8)
 103  *  \param info    Set info to 0 to use random initial residual vector,
 104  *                 or to 1 if you provide a one. On output, info=0 means
 105  *                 normal exit, 1 that max number of iterations was reached,
 106  *                 and 3 that no shifts could be applied. Negative numbers
 107  *                 correspond to errors in the arguments provided.
 108  */
 109 void
 110 F77_FUNC(dsaupd,DSAUPD)(int *     ido,
 111                         const char *    bmat,
 112                         int *     n,
 113                         const char *      which,
 114                         int *     nev,
 115                         double *  tol,
 116                         double *  resid,
 117                         int *     ncv,
 118                         double *  v,
 119                         int *     ldv,
 120                         int *     iparam,
 121                         int *     ipntr,
 122                         double *  workd,
 123                         int *     iwork,
 124                         double *  workl,
 125                         int *     lworkl,
 126                         int *     info);
 127
 128
 129
 130 /*! \brief Get eigenvalues/vectors after Arnoldi iteration, double prec.
 131  *
 132  *  See the ARPACK site for details. You must have finished the interative
 133  *  part with dsaupd() before calling this function.
 134  *
 135  *  \param rvec    1 if you want eigenvectors, 0 if not.
 136  *  \param howmny  'A' if you want all nvec vectors, 'S' if you
 137  *                 provide a subset selection in select[].
 138  *  \param select  Integer array, dimension nev. Indices of the
 139  *                 eigenvectors to calculate. Fortran code means we
 140  *                 start counting on 1. This array must be given even in
 141  *                 howmny is 'A'. (Arpack documentation is wrong on this).
 142  *  \param d       Double precision array, length nev. Eigenvalues.
 143  *  \param z       Double precision array, n*nev. Eigenvectors.
 144  *  \param ldz     Leading dimension of z. Normally n.
 145  *  \param sigma   Shift if iparam[6] is 3,4, or 5. Ignored otherwise.
 146  *  \param bmat    Provide the same argument as you did to dsaupd()
 147  *  \param n       Provide the same argument as you did to dsaupd()
 148  *  \param which   Provide the same argument as you did to dsaupd()
 149  *  \param nev     Provide the same argument as you did to dsaupd()
 150  *  \param tol     Provide the same argument as you did to dsaupd()
 151  *  \param resid   Provide the same argument as you did to dsaupd()
 152  *                 The array must not be touched between the two function calls!
 153  *  \param ncv     Provide the same argument as you did to dsaupd()
 154  *  \param v       Provide the same argument as you did to dsaupd()
 155  *                 The array must not be touched between the two function calls!
 156  *  \param ldv     Provide the same argument as you did to dsaupd()
 157  *  \param iparam  Provide the same argument as you did to dsaupd()
 158  *                 The array must not be touched between the two function calls!
 159  *  \param ipntr   Provide the same argument as you did to dsaupd()
 160  *                 The array must not be touched between the two function calls!
 161  *  \param workd   Provide the same argument as you did to dsaupd()
 162  *                 The array must not be touched between the two function calls!
 163  *  \param workl   Double precision work array, length lwork.
 164  *                 The array must not be touched between the two function calls!
 165  *  \param lworkl  Provide the same argument as you did to dsaupd()
 166  *  \param info    Provide the same argument as you did to dsaupd()
 167  */
 168 void
 169 F77_FUNC(dseupd,DSEUPD)(int *     rvec,
 170                         const char *    howmny,
 171                         int *     select,
 172                         double *  d,
 173                         double *  z,
 174                         int *     ldz,
 175                         double *  sigma,
 176                         const char *    bmat,
 177                         int *     n,
 178                         const char *    which,
 179                         int *     nev,
 180                         double *  tol,
 181                         double *  resid,
 182                         int *     ncv,
 183                         double *  v,
 184                         int *     ldv,
 185                         int *     iparam,
 186                         int *     ipntr,
 187                         double *  workd,
 188                         double *  workl,
 189                         int *     lworkl,
 190                         int *     info);
 191
 192
 193
 194
 195
 196 /*! \brief Implicitly Restarted Arnoldi Iteration, single precision.
 197  *
 198  *  Reverse communication interface for the Implicitly Restarted Arnoldi
 199  *  Iteration.  For symmetric problems this reduces to a variant of the
 200  *  Lanczos method. See the ARPACK site for details.
 201  *
 202  *  \param ido     Reverse communication flag. Set to 0 first time.
 203  *                 Upon return with ido=-1 or ido=1 you should calculate
 204  *                 Y=A*X and recall the routine. Return with ido=2 means
 205  *                 Y=B*X should be calculated. ipntr[0] is the pointer in
 206  *                 workd for X, ipntr[1] is the index for Y.
 207  *                 Return with ido=99 means it finished.
 208  *  \param bmat    'I' for standard eigenproblem, 'G' for generalized.
 209  *  \param n       Order of eigenproblem.
 210  *  \param which   Which eigenvalues to calculate. 'LA' for largest
 211  *                 algebraic, 'SA' for smallest algebraic, 'LM' for largest
 212  *                 magnitude, 'SM' for smallest magnitude, and finally
 213  *                 'BE' (both ends) to calculate half from each end of
 214  *                 the spectrum.
 215  *  \param nev     Number of eigenvalues to calculate. 0<nev<n.
 216  *  \param tol     Tolerance. Machine precision of it is 0.
 217  *  \param resid   Optional starting residual vector at input if info=1,
 218  *                 otherwise a random one is used. Final residual vector on
 219  *                 return.
 220  *  \param ncv     Number of columns in matrix v.
 221  *  \param v       N*NCV matrix. V contain the Lanczos basis vectors.
 222  *  \param ldv     Leading dimension of v.
 223  *  \param iparam  Integer array, size 11. Same contents as arpack.
 224  *  \param ipntr   Integer array, size 11. Points to starting locations
 225  *                 in the workd/workl arrays. Same contents as arpack.
 226  *  \param workd   Single precision work array, length 3*n+4.
 227  *                 Provide the same array for all calls, and don't touch it.
 228  *                 IMPORTANT: This is 4 units larger than standard ARPACK!
 229  *  \param iwork   Integer work array, size 80.
 230  *                 Provide the same array for all calls, and don't touch it.
 231  *                 IMPORTANT: New argument compared to standard ARPACK!
 232  *  \param workl   Single precision work array, length lwork.
 233  *  \param lworkl  Length of the work array workl. Must be at least ncv*(ncv+8)
 234  *  \param info    Set info to 0 to use random initial residual vector,
 235  *                 or to 1 if you provide a one. On output, info=0 means
 236  *                 normal exit, 1 that max number of iterations was reached,
 237  *                 and 3 that no shifts could be applied. Negative numbers
 238  *                 correspond to errors in the arguments provided.
 239  */
 240 GMX_LIBGMX_EXPORT
 241 void
 242 F77_FUNC(ssaupd,SSAUPD)(int *     ido,
 243                         const char *    bmat,
 244                         int *     n,
 245                         const char *    which,
 246                         int *     nev,
 247                         float *   tol,
 248                         float *   resid,
 249                         int *     ncv,
 250                         float *   v,
 251                         int *     ldv,
 252                         int *     iparam,
 253                         int *     ipntr,
 254                         float *   workd,
 255                         int *     iwork,
 256                         float *   workl,
 257                         int *     lworkl,
 258                         int *     info);
 259
 260
 261
 262
 263
 264 /*! \brief Get eigenvalues/vectors after Arnoldi iteration, single prec.
 265  *
 266  *  See the ARPACK site for details. You must have finished the interative
 267  *  part with ssaupd() before calling this function.
 268  *
 269  *  \param rvec    1 if you want eigenvectors, 0 if not.
 270  *  \param howmny  'A' if you want all nvec vectors, 'S' if you
 271  *                 provide a subset selection in select[].
 272  *  \param select  Integer array, dimension nev. Indices of the
 273  *                 eigenvectors to calculate. Fortran code means we
 274  *                 start counting on 1. This array must be given even in
 275  *                 howmny is 'A'. (Arpack documentation is wrong on this).
 276  *  \param d       Single precision array, length nev. Eigenvalues.
 277  *  \param z       Single precision array, n*nev. Eigenvectors.
 278  *  \param ldz     Leading dimension of z. Normally n.
 279  *  \param sigma   Shift if iparam[6] is 3,4, or 5. Ignored otherwise.
 280  *  \param bmat    Provide the same argument as you did to ssaupd()
 281  *  \param n       Provide the same argument as you did to ssaupd()
 282  *  \param which   Provide the same argument as you did to ssaupd()
 283  *  \param nev     Provide the same argument as you did to ssaupd()
 284  *  \param tol     Provide the same argument as you did to ssaupd()
 285  *  \param resid   Provide the same argument as you did to ssaupd()
 286  *                 The array must not be touched between the two function calls!
 287  *  \param ncv     Provide the same argument as you did to ssaupd()
 288  *  \param v       Provide the same argument as you did to ssaupd()
 289  *                 The array must not be touched between the two function calls!
 290  *  \param ldv     Provide the same argument as you did to ssaupd()
 291  *  \param iparam  Provide the same argument as you did to ssaupd()
 292  *                 The array must not be touched between the two function calls!
 293  *  \param ipntr   Provide the same argument as you did to ssaupd()
 294  *                 The array must not be touched between the two function calls!
 295  *  \param workd   Provide the same argument as you did to ssaupd()
 296  *                 The array must not be touched between the two function calls!
 297  *  \param workl   Single precision work array, length lwork.
 298  *                 The array must not be touched between the two function calls!
 299  *  \param lworkl  Provide the same argument as you did to ssaupd()
 300  *  \param info    Provide the same argument as you did to ssaupd()
 301  */
 302 GMX_LIBGMX_EXPORT
 303 void
 304 F77_FUNC(sseupd,SSEUPD)(int *     rvec,
 305                         const char *    howmny,
 306                         int *     select,
 307                         float *   d,
 308                         float *   z,
 309                         int *     ldz,
 310                         float *   sigma,
 311                         const char *    bmat,
 312                         int *     n,
 313                         const char *    which,
 314                         int *     nev,
 315                         float *   tol,
 316                         float *   resid,
 317                         int *     ncv,
 318                         float *   v,
 319                         int *     ldv,
 320                         int *     iparam,
 321                         int *     ipntr,
 322                         float *   workd,
 323                         float *   workl,
 324                         int *     lworkl,
 325                         int *     info);
 326
 327 #ifdef __cplusplus
 328 }
 329 #endif
 330
 331 #endif
 332