svdsc.rst.txt

c

C Library Interface

2.0

The PRIMME SVDS interface is composed of the following functions. To solve real and complex singular value problems call respectively:

not text

int :cdprimme_svds <dprimme_svds> (double *svals, double *svecs, double *resNorms,

primme_svds_params *primme_svds)

int :czprimme_svds <zprimme_svds> (double *svals, :cPRIMME_COMPLEX_DOUBLE *svecs,

double *resNorms, primme_svds_params *primme_svds)

text

int dprimme_svds(double *svals, double *svecs, double *resNorms, 
            primme_svds_params *primme);

int zprimme_svds(double *svals, PRIMME_COMPLEX_DOUBLE *svecs, double *resNorms, 
            primme_svds_params *primme);

There are more versions for matrix problems working in other precisions:

Precision	Real	Complex
half	:chprimme_svds :chsprimme_svds	:ckprimme_svds :cksprimme_svds
single	:csprimme_svds	:ccprimme_svds
double	:cdprimme_svds	:czprimme_svds

Other useful functions:

not text

void :cprimme_svds_initialize <primme_svds_initialize> (primme_svds_params *primme_svds) int :cprimme_svds_set_method <primme_svds_set_method> (primme_svds_preset_method method, primme_preset_method methodStage1, primme_preset_method methodStage2, primme_svds_params *primme_svds) void :cprimme_svds_display_params <primme_svds_display_params> (primme_svds_params primme_svds) void :cprimme_svds_free <primme_svds_free> (primme_svds_params *primme_svds)

text

void primme_svds_initialize(primme_svds_params *primme_svds);
int primme_svds_set_method(primme_svds_preset_method method,
      primme_preset_method methodStage1, primme_preset_method methodStage2,
      primme_svds_params *primme_svds);
void primme_svds_display_params(primme_svds_params primme_svds);
void primme_svds_Free(primme_svds_params *primme_svds);

PRIMME SVDS stores its data on the structure :cprimme_svds_params. See svds-guide-params for an introduction about its fields.

Running

To use PRIMME SVDS, follow these basic steps.

1. Include:

   #include "primme.h"   /* header file is required to run primme */

2. Initialize a PRIMME SVDS parameters structure for default settings:

   not text

   :cprimme_svds_params primme_svds; :cprimme_svds_initialize <primme_svds_initialize> (&primme_svds);

   text

   primme_svds_params primme_svds;
   
   primme_svds_initialize(&primme_svds);

3. Set problem parameters (see also svds-guide-params), and, optionally, set one of the :cpreset methods <primme_svds_preset_method>:

   not text

   primme_svds. = matrixMatvec; /* MV product */ primme_svds. = 1000; /* set the matrix dimensions */ primme_svds. = 100; primme_svds. = 10; /* Number of singular values */ :cprimmesvds_set_method <primme_svds_set_method> (primme_svds_hybrid, PRIMME_DEFAULT_METHOD, PRIMME_DEFAULT_METHOD, &primme_svds); ...

   text

   primme_svds.matrixMatvec = matrixMatvec; /* MV product */
   primme_svds.m = 1000;                    /* set problem dimension */
   primme_svds.n = 100;
   primme_svds.numSvals = 10;    /* Number of wanted singular values */
   primme_svds_set_method(primme_svds_hybrid, PRIMME_DEFAULT_METHOD,
                             PRIMME_DEFAULT_METHOD, &primme_svds);
   ...

4. Then to solve a real singular value problem call:

   not text

   ret = :cdprimme_svds <dprimme_svds> (svals, svecs, resNorms, &primme_svds);

   text

   ret = dprimme_svds(svals, svecs, resNorms, &primme_svds);

   The previous is the double precision call. There is available calls for complex double, single and complex single; check :czprimme_svds, :csprimme_svds and :ccprimme_svds.

   To solve complex singular value problems call:

   not text

   ret = :czprimme_svds <zprimme_svds> (svals, svecs, resNorms, &primme_svds);

   text

   ret = zprimme_svds(svals, svecs, resNorms, &primme_svds);

   The call arguments are:

   • svals, array to return the found singular values;
   • svecs, array to return the found left and right singular vectors;
   • resNorms, array to return the residual norms of the found triplets; and
   • ret, returned error code.

5. To free the work arrays in PRIMME SVDS:

   not text

   :cprimme_svds_free <primme_svds_Free> (&primme_svds);

   text

   primme_svds_free(&primme_svds);

Parameters Guide

PRIMME SVDS stores the data on the structure :cprimme_svds_params, which has the next fields:

not text

Basic
PRIMME_INT , number of rows of the matrix.
PRIMME_INT , number of columns of the matrix.
void (* )(...), matrix-vector product.
int , how many singular triplets to find.
primme_svds_target , which singular values to find.
double , tolerance of the residual norm of converged triplets.

For parallel programs
int , number of processes
int , rank of this process
PRIMME_INT , number of rows stored in this process
PRIMME_INT , number of columns stored in this process
void (* )(...), sum reduction among processes

Accelerate the convergence
void (* )(...), preconditioner-vector product.
int , initial vectors as approximate solutions.
int
int
int

User data
void *
void *
void *
void *
void *

Advanced options
int , for targeting interior singular values.
double *
int , orthogonal constrains to the singular vectors.
int
PRIMME_INT
PRIMME_INT [4]
double
int
FILE *
primme_svds_operator
primme_svds_operator


void (* )(...), custom convergence criterion.
void (* )(...), custom convergence history.
primme_op_datatype
primme_op_datatype
primme_op_datatype
primme_op_datatype
primme_op_datatype

text

/* Basic */
PRIMME_INT m;                    // number of rows of the matrix
PRIMME_INT n;                 // number of columns of the matrix
void (*matrixMatvec)(...);              // matrix-vector product
int numSvals;              // how many singular triplets to find
primme_svds_target target;      // which singular values to find
double eps;               // tolerance of the converged triplets

/* For parallel programs */
int numProcs;          // number of processes
int procID;            // rank of this process
PRIMME_INT mLocal;     // number of rows stored in this process
PRIMME_INT nLocal;     // number of columns stored in this process
void (*globalSumReal)(...); // sum reduction among processes

/* Accelerate the convergence */
void (*applyPreconditioner)(...); // preconditioner-vector product
int initSize;        // initial vectors as approximate solutions
int maxBasisSize;
int minRestartSize;
int maxBlockSize;

/* User data */
void *commInfo;
void *matrix;
void *preconditioner;
void *convtest;
void *monitor;

/* Advanced options */
int numTargetShifts;        // for targeting interior values
double *targetShifts;
int numOrthoConst;   // orthogonal constrains to the vectors
int locking;
PRIMME_INT maxMatvecs;
PRIMME_INT iseed[4];
double aNorm;
int printLevel;
FILE * outputFile;
primme_svds_operator method;
primme_svds_operator methodStage2;
primme_params primme;
primme_params primmeStage2;
void (*convTestFun)(...); // custom convergence criterion
void (*monitorFun)(...); // custom convergence history
primme_op_datatype matrixMatvec_type;
primme_op_datatype applyPreconditioner_type;
primme_op_datatype globalSumReal_type;
primme_op_datatype broadcastReal_type;
primme_op_datatype internalPrecision;

PRIMME SVDS requires the user to set at least the matrix dimensions ( x ) and the matrix-vector product (), as they define the problem to be solved. For parallel programs, , , and are also required.

In addition, most users would want to specify how many singular triplets to find, and provide a preconditioner (if available).

It is useful to have set all these before calling :cprimme_svds_set_method. Also, if users have a preference on , , etc, they should also provide them into :cprimme_svds_params prior to the :cprimme_svds_set_method call. This helps :cprimme_svds_set_method make the right choice on other parameters. It is sometimes useful to check the actual parameters that PRIMME SVDS is going to use (before calling it) or used (on return) by printing them with :cprimme_svds_display_params.

Interface Description

The next enumerations and functions are declared in primme.h.

?primme_svds

magma_?primme_svds

primme_svds_initialize

primme_svds_create

primme_svds_set_method

primme_svds_display_params

primme_svds_free

primme_svds_params_destroy