primme

NAME Nim interface for PRIMME: PReconditioned Iterative MultiMethod Eigensolver

DESCRIPTION This is a Nim interface for PRIMME. "PRIMME, pronounced as prime, computes a few eigenvalues and their corresponding eigenvectors of a real symmetric or complex Hermitian matrix. It can also compute singular values and vectors of a square or rectangular matrix. It can find largest, smallest, or interior singular/eigenvalues and can use preconditioning to accelerate convergence. It is especially optimized for large, difficult problems, and can be a useful tool for both non-experts and experts."

 The Nim interfrace tries to stick to the C interface while
 using Nim's capabilities to make our life easier.  Some
 familiarity with the C interface is recommended in using the
 Nim interface.

 There are three opaque types corresponding the C interface,

   PRIMME_INT
   PRIMME_COMPLEX_FLOAT
   PRIMME_COMPLEX_DOUBLE

 Following the C interface, you can set PRIMME_INT_SIZE at compile
 time, which has a default value of

   const PRIMME_INT_SIZE* {.strdefine.} = "64"

 However, you need to make sure that the PRIMME C library is built
 with the same value of PRIMME_INT_SIZE.

 The main driver is a set of procedures all named `run'.

   run(primme, vals, vecs, resNorms)

 where `primme' is either `primme_params' or
 `primme_svds_params', `vals' and `resNorms' holds the eigen
 (singular) values and their residual norms respectively, and
 `vecs' holds the eigen (singular) vectors.

 The default parameters object `primme_params' and
 `primme_svds_params' can be obtained from
 `primme_initialize' and `primme_svds_initialize'
 respectively.  Method can be given by calling `set_method'
 with the parameters object and supplying
 `primme_preset_method' and/or `primme_svds_preset_method'.
 The parameters can be displayed with `display_params', and
 freed with `free'.

 A helper template `asarray[T](p:pointer)' can be used to
 simplify interfacing with C libraries that give us pointers.

   asarray[T](p)

 converts any pointer to type `ptr array[0..0,T]'.

 A custom `ccomplex[T]' is provided via the module
 primme/ccomplex.  It is designed such that `ccomplex[cfloat]` and
 `ccomplex[cdouble]` are binary compatible with
 `PRIMME_COMPLEX_FLOAT' and `PRIMME_COMPLEX_DOUBLE' respectively.

 In addition to the above described interface, the Nim module
 also exposes all C library types, enums, and functions,
 declared via the header file, `primme.h'.

SYNPOSIS const PRIMME_INT_SIZE {.strdefine.} type PRIMME_INT type PRIMME_COMPLEX_FLOAT type PRIMME_COMPLEX_DOUBLE proc run(primme: var primme_params; evals: var openarray[cfloat]; evecs: var openarray[cfloat]; resNorms: var openarray[cfloat]): int proc run(primme: var primme_params; evals: var openarray[cfloat]; evecs: var openarray[ccomplex[cfloat]]; resNorms: var openarray[cfloat]): int proc run(primme: var primme_params; evals: var openarray[cdouble]; evecs: var openarray[cdouble]; resNorms: var openarray[cdouble]): int proc run(primme: var primme_params; evals: var openarray[cdouble]; evecs: var openarray[ccomplex[cdouble]]; resNorms: var openarray[cdouble]): int proc run(primme: var primme_svds_params; svals: var openarray[cfloat]; svecs: var openarray[cfloat]; resNorms: var openarray[cfloat]): int proc run(primme: var primme_svds_params; svals: var openarray[cfloat]; svecs: var openarray[ccomplex[cfloat]]; resNorms: var openarray[cfloat]): int proc run(primme: var primme_svds_params; svals: var openarray[cdouble]; svecs: var openarray[cdouble]; resNorms: var openarray[cdouble]): int proc run(primme: var primme_svds_params; svals: var openarray[cdouble]; svecs: var openarray[ccomplex[cdouble]]; resNorms: var openarray[cdouble]): int proc primme_initialize:primme_params proc primme_svds_initialize:primme_svds_params proc set_method(primme: var primme_params; preset_method: primme_preset_method): int proc set_method(primme: var primme_svds_params; preset_method: primme_svds_preset_method; methodStage1: primme_preset_method; methodStage2: primme_preset_method): int template display_params(primme: primme_params) template display_params(primme: primme_svds_params) proc free(primme: var primme_params) proc free(primme: var primme_svds_params) template asarray*T:untyped

BUILDING To compile and link against PRIMME library, Nim needs to know its location and any extra libraries required. The default flags in `primme.nim'

   const
     primmeDir {.strdefine.} = "/usr"
     primmeLib {.strdefine.} = primmeDir&"/lib/libprimme.a"
     lapackLib {.strdefine.} = "/usr/lib/libopenblas.a -lm -lgfortran"
   {.passC: "-I"&primmeDir&"/include".}
   {.passL: primmeLib&" "&lapackLib.}

 are unsuitable for every situation.  You can pass custom
 flags to the Nim compiler when compiling your application
 with

   nim c -d:primmeDir=$HOME/pkg/primme \
         -d:lapackLib="-llapack -lblas -lm" \
     YourApp.nim

EXAMPLES See files under the directory, `test'.

LICENSE This work is licensed under the MIT license. See file LICENSE for details.

SEE ALSO PRIMME: PReconditioned Iterative MultiMethod Eigensolver https://github.com/primme/primme